Guide

#Language Overview

hd-lang is a statically typed language for software generated with AI and reviewed by humans. It targets WebAssembly and favors source code whose data, dependencies, authority, failure paths, and runtime boundaries remain visible without relying on framework conventions or string parsing.

The language is designed around two primary settings:

1. interactive scripts and typed tool calls inside AI agents;
2. engineering and infrastructure code generated by AI.

The use scenarios describe those settings in detail. This overview focuses on the common design that serves both.

#Design Priorities

#Readable, explicit programs

Python-style indentation keeps common code compact. Explicit types, nominal struct declarations, traits, visible error values, and declared dependencies make larger programs reviewable. The language avoids hidden registration, ambient authority, and behavior inferred from naming conventions.

#Static structure for tools

The compiler understands program structure rather than asking external tools to recover it from strings or runtime reflection. Typed declarations, requirements, and annotations can support schema generation, validation, deployment adapters, diagnostics, and automated repair while remaining normal language constructs.

#A small language/runtime boundary

Core semantics live in the language. Testing frameworks, workflow engines, observability exporters, persistence, incremental computation, and deployment integration build on those semantics through libraries, compiler tooling, and the runtime. They do not each introduce separate syntax.

#Core Model

#Data, traits, and explicit failure

Programs model application data with nominal struct and enum declarations. Traits express shared behavior and generic constraints, with explicit conformance. Absence is represented by T?; recoverable failure is represented by Result[T, E]. Panics are reserved for defects and violated runtime contracts rather than ordinary application errors.

Structs, enums, tuples, List, Map, and string are values: assigning, passing, or returning one copies it, and a copy never changes the original. Sharing is written where it happens. &T reads a value where it lives, &mut T also writes it, and &mut T { ... } makes a new object that every holder of the reference sees change. let mut marks a variable whose value changes in place, and a method that changes its receiver says &mut self. A &mut reference is not exclusive, so it expresses permission to write, not ownership or uniqueness.

#Requirements, providers, and suspension

hd-lang separates three concerns that are often combined in one effects or dependency framework:

1. requirement rows declare which services a function needs;
2. provider contexts supply those services explicitly;
3. fn! and Suspend[T] represent cold, one-shot computations that may suspend.

Requirements are traits, so capabilities such as storage, networking, clocks, or observability have typed interfaces. Missing providers are compile-time errors below a registered boundary; a boundary's host bindings are checked before execution. A suspension captures its arguments and providers when constructed, then runs at most once when driven.

This separation prevents ambient provider lookup and requirement-row erasure at call sites without treating ordinary errors as effects. Provider values are ordinary values that may escape their provider scope, so a requirement row does not audit authority that flows through values.

#Typed annotations

Annotations attach typed metadata to declarations, and typed derivation turns compiler-verified structure into ordinary trait implementations. They do not silently change a declaration's type, behavior, name, visibility, or registration status.

The same model can support validation, schemas, database metadata, user interfaces, retention policies, and other structural information. Libraries define the meaning of that information; the language supplies attachment and derivation.

#WebAssembly execution

hd-lang targets WebAssembly with reference counting and cycle collection and a WASI-compatible host boundary. Authority-bearing providers originate at that boundary, allowing runtimes to sandbox code and record meaningful operations. Durable execution and replay are runtime protocols over explicit suspensions rather than serialization of an active Wasm stack.

#Document Boundaries

• The tour and Learn hd-lang in 10 Minutes teach the accepted language through examples.
• The formal specification defines normative syntax and semantics.
• Use Scenarios records product requirements and expected workflows.
• Future Work contains unresolved and exploratory design work.

When these documents differ, the formal specification is authoritative.