# Part 1: Getting Started

Source: https://dovetaillang.org/book/getting-started/


## 1.1 Introduction to Dovetail

### What is Dovetail?

Dovetail is a new high-level programming language designed for writing business-logic heavy applications. It compiles to WebAssembly (specifically WasmGC), prioritizing fast compilation and great tooling over raw runtime performance.

Dovetail is:

- **Expression-based** - Everything is an expression that returns a value
- **Strongly typed** - A powerful type system catches errors at compile time
- **Layout-sensitive** - Uses indentation instead of curly braces and semicolons
- **Functional-first** - Encourages immutability and pure functions, while supporting imperative and object-oriented styles
- **Garbage collected** - Memory management is handled automatically
- **Async-first** - Built-in async/await with elegant error propagation
- **No exceptions** - Errors are values using `Result` and `Option` types with railway-oriented programming

### Why Another Language?

Rust is a modern language for system-level programming, written from the ground up with modern concepts and a new ecosystem. It didn't inherit old baggage from VMs or C/C++.

But we don't have such a language for high-level programming.

**TypeScript** - A great language with modern concepts, but it's based on JavaScript with the JavaScript ecosystem and a lot of baggage:
- Both async and callbacks
- Exceptions
- Nulls
- Inconsistency across the ecosystem (typed/untyped libraries)
- No ad-hoc polymorphism (traits, typeclasses)

**Python** - Popular but problematic for large codebases:
- Exceptions
- Nulls
- Untyped by default
- Both async and sync APIs
- Inconsistency in the ecosystem (is it typed or not? are all dependencies typed?)
- No ad-hoc polymorphism

**Java** - Mature but carrying decades of baggage:
- No async/await
- Type erasure
- Nulls
- Exceptions
- No standard across tools (formatter, build tool)
- No tuples
- No ad-hoc polymorphism

**Kotlin** - Modern features on top of Java, but still inherits Java's baggage:
- JVM type erasure
- Exceptions
- Null safety is incomplete - the JVM isn't null-safe, so you can encounter nulls at runtime from Java interop
- Standard library split between Kotlin and Java APIs
- No ad-hoc polymorphism

**Scala** - Powerful type system but with significant drawbacks:
- Inherits Java/JVM baggage
- Slow compilation times
- High learning curve
- Null safety is incomplete - JVM interop can introduce nulls at runtime
- Has ad-hoc polymorphism (implicits/givens), but at the cost of compilation performance and complexity

**Go** - Simple and fast to compile, but a limited type system:
- No sum types (discriminated unions)
- Limited generics (added recently, still maturing)
- Nulls (nil pointers)
- No async/await and no way to extend the language with custom coroutines
- Interfaces provide basic ad-hoc polymorphism, but more limited than traits (no associated types, can't extend types you don't own)

**C#** - Modern features but carrying .NET legacy:
- Standard library supports multiple models for backward compatibility
- Nullable reference types are opt-in and incomplete
- Exceptions
- No ad-hoc polymorphism

**Rust** - Amazing but low-level:
- No garbage collection
- Not optimized for compile times
- Steep learning curve for business logic developers

**What is ecosystem baggage?**

When we say "ecosystem baggage," we mean:
- Legacy constructs in the language that exist for backward compatibility
- Standard libraries supporting multiple patterns (sync/async, exceptions/results, nullable/non-nullable)
- Half-baked null safety solutions where the runtime can still produce nulls even when the type system says otherwise
- Inconsistent tooling where the community is split across multiple formatters, build tools, and conventions

**We need a new language** - one with modern concepts and no ecosystem baggage. Dovetail is that language: garbage collected, fast to compile, with a clean type system, proper error handling, and consistent tooling from day one.

### Design Philosophy and Principles

Dovetail is built around several core principles:

**Fast Compilation**

Compilation should feel instant. Dovetail prioritizes fast feedback loops over maximum runtime optimization. The target competition is Python and Node.js: the goal is to pair their productive development experience with the performance opportunities of compiled WebAssembly.

**Beautiful Code**

Dovetail is designed to produce readable code that flows like English:

- String interpolation without prefixes: `"Hello, $name!"`
- Named arguments for clarity: `createUser(name = "John", age = 30)`
- Layout-sensitive syntax eliminates visual noise
- No cryptic abbreviations - `function` not `fn`, `Comparable` not `Ord`, `Equatable` not `Eq`
- Keywords instead of operators where it improves readability (`and`, `or`, `not`)

**Strong Type System**

The type system helps eliminate bugs:

- No null values - use `Option<T>` instead
- Discriminated unions (enums) for modeling data
- Traits for shared behavior
- Result types for error handling - no exceptions

**Great Tooling**

Dovetail includes excellent tools from day one:

- Integrated package manager and build tool
- Language Server Protocol (LSP) support
- Built-in formatter with `dovetail fmt` and format-on-save in VS Code
- Built-in skills for coding agents - Guidance for writing idiomatic Dovetail, applying best practices, and using specialized sub-agents for code review (planned for the public release)
- REPL for exploration (planned)

### Target Platform (WasmGC)

Dovetail compiles to WebAssembly with Garbage Collection (WasmGC). This provides:

- **Portability** - Target hosts that support WasmGC and the WASI interfaces your program uses
- **Performance** - Designed for near-native execution through WebAssembly and Wasmtime.
- **Safety** - WebAssembly's sandboxed execution model
- **Interoperability** - Use WASI for system access

Dovetail targets WebAssembly 3.0 and WASI Preview 3. `dovetail run` uses Wasmtime for local execution; you can also deploy the compiled component to other hosts that support the required WebAssembly features and WASI interfaces.

Dovetail uses traits for generic behavior and interfaces for contracts that can
also be stored and passed as values. See [Interfaces and Interface Types](https://dovetaillang.org/book/type-system.md#611-interfaces-and-interface-types)
and [Traits and Implementations](https://dovetaillang.org/book/traits.md).

### Comparison with Other Languages

This is a high-level comparison of the design choices motivating Dovetail. Fast compilation is a design goal, not a benchmark result; ecosystem consistency is the direction we are building toward.

| Feature | Dovetail | TypeScript | Python | Java | Kotlin | Go | C# | Rust |
|---------|--------|------------|--------|------|--------|-----|-----|------|
| No Nulls | Yes | No | No | No | Partial | No | Partial | Yes |
| No Exceptions | Yes | No | No | No | No | Yes | No | Yes |
| Consistent Async | Yes | No | No | No | Yes | No | Yes | Yes |
| Ad-hoc Polymorphism (Traits) | Yes | No | No | No | No | Partial | No | Yes |
| Sum Types | Yes | Yes | No | No | Yes | No | No | Yes |
| Layout-Sensitive | Yes | No | Yes | No | No | No | No | No |
| Garbage Collected | Yes | Yes | Yes | Yes | Yes | Yes | Yes | No |
| Fast Compilation | Yes | Yes | Yes | No | No | Yes | No | No |
| No Ecosystem Baggage | Yes | No | No | No | No | No | No | Yes |

---

## 1.2 Installation and Setup

### Installing prebuilt binaries

No Rust toolchain is needed. The CLI includes the runtime used by `dovetail run`.

On macOS (Intel or Apple Silicon) and Linux (x86_64 or ARM64, glibc):

```sh
curl -fsSL https://dovetaillang.org/install.sh | sh
```

On Windows x64, use PowerShell:

```powershell
irm https://dovetaillang.org/install.ps1 | iex
```

The scripts install the website's release and verify the executable's SHA-256
checksum before replacing an existing installation. macOS and Linux require
`curl` and either `sha256sum` or `shasum`. Linux binaries use glibc and need a system
compatible with the Ubuntu 24.04 build environment; Alpine/musl is not supported.

The default directory is `~/.local/bin` on macOS/Linux and
`%LOCALAPPDATA%\Dovetail\bin` on Windows. Add it to your `PATH` as printed by the
installer. The scripts do not edit your shell profile or Windows environment.

For a specific release or installation directory, download the script first:

```sh
curl -fsSL https://dovetaillang.org/install.sh -o install.sh
sh install.sh --version v0.1.4 --install-dir "$HOME/.local/bin"
```

PowerShell scripts accept `-Version v0.1.4` and `-InstallDir PATH`. Both scripts
are served by this website and download binaries from the matching
[GitHub release](https://github.com/somdoron/dovetail/releases).

### Installing with Cargo

With a [Rust toolchain](https://rustup.rs/) installed, build the Dovetail CLI from crates.io with:

```bash
cargo install dovetail-lang --locked
```

`dovetail-lang` is the package name; the command you run is `dovetail`. Cargo builds
and installs the executable in its bin directory (usually `~/.cargo/bin/`). Make
sure that directory is on your `PATH`. The CLI includes the runtime used by
`dovetail run`, so you don't need to install Wasmtime separately.

`cargo install dovetail-lang` also works; `--locked` uses the dependency versions
recorded for the release.

### Installing from Source

To try the current development version or work on the compiler, install from a
repository checkout instead:

1. **Clone the repository:**

```bash
git clone https://github.com/somdoron/dovetail.git
cd dovetail
```

2. **Build the project:**

```bash
cargo build --release
```

3. **Install the Dovetail CLI:**

```bash
cargo install --path dovetail --locked
```

This installs the `dovetail` command to your Cargo bin directory (usually `~/.cargo/bin/`).

### Verifying the Installation

Verify Dovetail is installed correctly:

```bash
dovetail --version
dovetail --help
```

The help output lists commands including `init`, `projects`, `deps`, `fmt`,
`build`, `check`, `run`, `test`, and `lsp-server`. Use `dovetail <command> --help`
for details about a particular command.

When working on the compiler itself, use `cargo run -- <command>` from its checkout
to test the current source. See [Tool Commands](https://dovetaillang.org/book/tool-commands.md) for more details.

---

## 1.3 Editor Setup

### VS Code Extension

Dovetail provides a VS Code extension for the best development experience.

#### Installing the Extension

Download `dovetail-language-<version>.vsix` from the matching
[GitHub release](https://github.com/somdoron/dovetail/releases). In VS Code, run
**Extensions: Install from VSIX...** from the Command Palette and select the file.
Install the compiler separately using the installation instructions above.

To build the extension from a repository checkout:

1. Open VS Code
2. Navigate to the `vscode-dovetail` directory in the Dovetail repository
3. Run:

```bash
npm ci
```

4. Package the extension:

```bash
npm run package
```

5. Install the generated `.vsix` file in VS Code:
   - Open Command Palette (Cmd/Ctrl + Shift + P)
   - Select "Extensions: Install from VSIX..."
   - Choose the generated `.vsix` file

### Extension Features

The Dovetail VS Code extension provides:

- **Syntax highlighting** - Colorized Dovetail code
- **LSP support** - Real-time error diagnostics, autocomplete, go-to-definition
- **Hover documentation** - View type information on hover
- **Find references** - Find all usages of a symbol
- **Workspace symbols** - Quick navigation to types and functions
- **Formatting** - Format a document or format automatically on save

### Configuration Options

The extension can be configured in VS Code settings:

| Setting | Default | Description |
|---------|---------|-------------|
| `dovetail.serverPath` | `"dovetail"` | Path to the Dovetail executable |
| `dovetail.serverConnection` | `"stdio"` | LSP transport (`stdio` or `tcp`) |
| `dovetail.serverPort` | `9257` | TCP port for LSP when dovetail.serverConnection is tcp |
| `dovetail.trace.server` | `"off"` | Trace communication with LSP server |

To enable format-on-save:

```json
{
  "[dovetail]": {
    "editor.defaultFormatter": "dovetail-lang.dovetail-language",
    "editor.formatOnSave": true
  }
}
```

See [Formatting](https://dovetaillang.org/guides/formatting.md) for the formatter's style and options.

---

## 1.4 Your First Dovetail Program

### Creating a Project with `dovetail init`

Create a new Dovetail project using the `init` command:

```bash
mkdir my-project
cd my-project
dovetail init hello
```

This creates:

- `Dovetail.toml` - The project manifest
- `.gitignore` - Excludes the local `.dovetail/` cache
- `hello/src/main.dove` - The main source file

For a library project, use `dovetail init mylib` and replace the generated `main`
with your library declarations. A library has no `main` entry point; `init` does
not have a separate `--lib` flag.

### The `Dovetail.toml` Manifest File

The generated `Dovetail.toml` looks like this (the compiler version matches the CLI you installed):

```toml
compiler-version = "0.1.4"

[[project]]
name = "hello"
root_package = "hello"
packages = ["."]
```

Key fields:

- `compiler-version` - The exact compiler version required by the workspace
- `[[project]]` - Project definition (can have multiple)
  - `name` - Project name
  - `root_package` - The root package name for this project
  - `packages` - Package directories relative to the project's `src/` directory

### Project Directory Structure

After running `dovetail init hello`, your directory looks like:

```
my-project/
├── .gitignore
├── Dovetail.toml
└── hello/
    └── src/
        └── main.dove
```

Convention:

- Each project has its own directory matching the project name
- Source files go in `src/`
- Test files go in `test/` (for integration tests)
- The directory structure under `src/` determines package names

### Writing "Hello, World!"

Open `hello/src/main.dove` and replace its contents with this complete example:

<!-- book-example: {"name": "hello", "depends": [], "stdout": "Hello, World!\n"} -->
```dovetail
package hello

function greeting(name: String): String = "Hello, $name!"

function main(): Unit = debug(greeting("World"))

test "greets the supplied name" =
    assert greeting("Dovetail") == "Hello, Dovetail!"
```

Let's break this down:

- `package hello` - Declares this file belongs to the `hello` package
- `function greeting(...)` - Builds a greeting using string interpolation
- `function main(): Unit` - The entry point for an application
- `=` followed by indented code - The function body
- `debug(...)` - Prints a value and a newline for a quick diagnostic
- `test "greets the supplied name"` - Checks the greeting with an assertion

This **complete example is checked in CI**. See [Book validation](https://dovetaillang.org/guides/book-validation.md)
for what is checked; other snippets in the book may show only part of a program.
For application console output with typed I/O errors, see
[`Console.writeLine` in the library guide](https://dovetaillang.org/book/stdlib.md#225-io).

### Building and Running

Run these commands from the directory containing `Dovetail.toml`.

**Format your code:**

```bash
dovetail fmt
```

Use `dovetail fmt --check` to check formatting without changing files.

**Build the project:**

```bash
dovetail build
```

This compiles your code and produces `build/hello.wasm`.

**Build and run:**

```bash
dovetail run
```

Output:

```
Hello, World!
```

**Type check without building:**

```bash
dovetail check
```

This verifies your code is correct without generating a WebAssembly file - useful for quick feedback during development.

**Run the test:**

```bash
dovetail test
```

The test checks that `greeting("Dovetail")` returns `"Hello, Dovetail!"`. You'll learn
more about testing in [Part 15](https://dovetaillang.org/book/testing.md).

---

## Summary

You now have Dovetail installed and know how to:

- Create a new project with `dovetail init`
- Understand the project structure and `Dovetail.toml`
- Write and run a simple program
- Use the VS Code extension for a better development experience

In the next part, we'll explore the Dovetail CLI commands in more detail.


---

# Part 2: Dovetail Tool Commands

Source: https://dovetaillang.org/book/tool-commands/


## 2.1 The Dovetail CLI

Run `dovetail --help` for commands and `dovetail <command> --help` for that command's
arguments. `dovetail --version` reports the compiler version. From a compiler
checkout, use `cargo run -- <command>` to avoid a stale installed binary.

| Command | Behavior |
|---|---|
| `dovetail init hello` | Create a workspace and optionally install coding-agent support |
| `dovetail ai install` | Install or refresh workspace-local coding-agent guidance |
| `dovetail projects add model` | Add a project and starter `main` to an existing workspace |
| `dovetail query <search/package/definition>` | Discover typed declarations in projects, dependencies, and the prelude |
| `dovetail check [project]` | Type-check all projects or one selected project and its dependencies |
| `dovetail build [project]` | Compile; writes artifacts under `build/` by default |
| `dovetail image build [-p project]` | Build precompiled Linux AMD64/ARM64 OCI images for configured projects |
| `dovetail image push [-p project]` | Publish existing image archives using Docker credentials |
| `dovetail run [project]` | Build and run an application's `main` |
| `dovetail test [project]` | Build and execute discovered tests |
| `dovetail fmt [files...]` | Format local workspace sources/tests, or explicit `.dove` files |
| `dovetail deps fetch` | Fetch declared Git selections and their transitive dependencies |
| `dovetail deps update [alias]` | Explicitly update all dependencies or one selected alias |
| `dovetail lsp-server` | Start the editor language server over stdio |

Run manifest-based commands from the workspace root. `fmt` and `query` also find a
manifest in an ancestor directory; explicit file formatting needs no manifest.
Specify the project when running a multi-project workspace.

### Coding-agent support

`dovetail ai install` installs a progressive language skill and two review profiles.
On first interactive use, select generic agents (including Codex), Claude, or both:

```sh
dovetail ai install --agent generic,claude
dovetail ai install --agent claude --dry-run
dovetail init hello --ai generic,claude
dovetail init hello --no-ai
```

Generic guidance installs under `.agents/skills/dovetail`; Claude uses
`.claude/skills/dovetail` and two `.claude/agents` wrappers. Reviews run only when
requested. Consumer `AGENTS.md` and `CLAUDE.md` files are left untouched.
Commit installed files, including their installation metadata, to share with a team.

The skill assets ship inside the `dovetail-lang` Cargo package and are embedded in
the executable, so `cargo install dovetail-lang` includes AI support. Installation
is offline and uses the executing compiler's bundled guidance. A later
bare `dovetail ai install` refreshes remembered targets; the skill recommends it if
its version differs from the compiler. Edited managed files cause a conflict report
before writing: preserve or resolve those edits and rerun. Explicit targets add or
refresh those targets without removing others. `--dry-run` previews changes.

The command finds the nearest ancestor workspace. Noninteractive first installation
requires `--agent`; noninteractive `init` skips the optional prompt unless `--ai` is
provided. Interactive `init` offers support after workspace creation. If optional
installation fails, the project remains created and the error gives a retry command.

### Checking, building, and testing

```sh
dovetail check hello
dovetail build hello --output-dir build
dovetail test hello --filter "greets"
dovetail test hello --file hello/src/main.dove
```

`--output-dir` also has the short form `-o`. Test filters match the fully qualified test name; repeated `--filter` arguments
are OR'd. `--file` selects a source path (workspace-relative paths are the least
ambiguous). Test output already includes individual results; there is no test
`--verbose` option. Tests can live in `src/` or the project's `test/` directory;
see [Testing](https://dovetaillang.org/book/testing.md).

Compiler warnings appear during checking, building, running, testing, and in the
editor. They do not fail compilation. Handle discarded `Result`, `Async`, and
`Resource` values or acknowledge an intentional discard with `let _ = ...`.
That acknowledgement does not execute deferred work.

### Container images

Configure `[project.image]` in `Dovetail.toml`, then use `dovetail image build`
and `dovetail image push`. Both select all image-configured local projects unless
`-p` selects one. Building produces local archives; pushing never rebuilds.
See the [container image guide](https://dovetaillang.org/guides/container-images.md) for base images,
runtime releases, project settings, and GitHub Actions publishing.

Image WASI grants (`allow-network`, `inherit-env`, and `allow-path` under
`[project.image.wasi]`) default to denied and are fixed at image build time.
There are no startup flag or environment-variable overrides; change the manifest
and rebuild. Mounts, port mappings, and environment values still need corresponding
WASI grants. See [Production Deployment and CI](https://dovetaillang.org/book/production-deployment.md) for
the complete workflow.

### Formatting

```sh
dovetail fmt
dovetail fmt --check
dovetail fmt hello/src/main.dove
```

The formatter uses four spaces and a 100-column target, preserves comments and
literal text, and checks the structure of its output before accepting it. It does
not fetch or format Git dependencies. It does not insert named arguments or
rewrite synchronous functions into async functions. See [Formatting](https://dovetaillang.org/guides/formatting.md).

### Runtime permissions

`run` denies filesystem, network, and inherited environment access unless granted.
Standard input/output are available. Grant only the capabilities the program uses:

```sh
dovetail run hello --allow-cwd
dovetail run server --allow-network
dovetail run worker --env MODE=development -- first-argument second-argument
```

| Run option | Grants |
|---|---|
| `--allow-cwd` | Current directory mounted at `.`; useful for relative file paths |
| `--allow-path PATH` | A specific host path, mounted at that path; repeatable |
| `--allow-root` | Entire host filesystem root |
| `--allow-network` | TCP, UDP, and DNS access |
| `--env KEY=VALUE` | One environment entry; repeatable |
| `--inherit-env` | All host environment entries; explicit `--env` entries override them |
| `-- ARGS...` | Application arguments |

These are options of `run`, not of `test`. The test runner supplies its own host
configuration. Built components also need a compatible host and that host's
permission configuration when executed outside `dovetail run`.

### Discover APIs with `query`

Use compiler-backed declaration queries to explore local projects, dependencies,
and the embedded prelude:

```bash
dovetail query search Connection
dovetail query search transaction --package standard.sqlite
dovetail query package
dovetail query package standard.sqlite
dovetail query definition standard.sqlite.Connection
dovetail query definition standard.sqlite.Connection.transaction
```

`search` returns matching declaration/member names, kinds, projects, and source
locations. Matching is case-insensitive, with exact matches ranked first. Use
`--limit` (default 50) and `--offset` to page results. `--package` restricts search
to that exact package, including members.

`package` lists available packages by project. With a name, it lists immediate
declarations and child packages. `definition` accepts a fully qualified name and
shows documentation and Dovetail signatures; a type and its same-name module are
shown together, and a member query includes its overloads.

Use `--project <name>` to select a local consumer's dependency context. Local
private/internal declarations are included; dependencies show public APIs and
protected subclass members by default. `--all` also exposes nonpublic dependency
declarations for inspection without changing their accessibility. If multiple
contexts provide different versions of a definition, select the intended consumer
with `--project`.

Definition output is a declaration view, **not compilable source**: executable
bodies, initializers, and superclass argument expressions are omitted. It preserves
bounds, modifiers, aliases, and associated types. Type definitions include related
implementation signatures and links to named extensions; importing an extension
remains necessary. Conditional implementation bounds still need to be satisfied.
Read source and tests when behavior cannot be established from signatures.

The embedded prelude can be queried outside a workspace. Dependency queries use
normal resolution, honor `--offline` and `--locked`, and do not request upgrades.
Normal resolution can populate caches and lockfiles. Queries do not emit WASM.

On analysis errors, recoverable declarations are marked `INCOMPLETE`, diagnostics
are printed to stderr, and the exit status is nonzero. Unavailable inferred types
are marked explicitly. A healthy library definition does not require its consumer
application to typecheck. Empty searches succeed; missing targets and ambiguous
or incomplete results fail.

### Language server

Editors normally launch `dovetail lsp-server` over stdio. For a TCP client, use
`dovetail lsp-server --tcp --port 9257`. `--verbose` enables server logging to stderr;
it is a language-server option, not a test option.

### Exit status

Successful commands return zero. Check/build failures return nonzero. Tests return
1 for test failures and 2 for compilation/setup failures; no matching tests returns
zero, so do not use an unchecked filter as proof that tests ran. `fmt --check`
returns 1 when files need formatting; formatter input or processing errors return 2.
CLI usage errors also return nonzero. Preserve exit status in CI rather than
swallowing failures with `|| echo ...`.

## 2.2 Project Structure

A workspace holds projects. Each project lists its source packages and project
dependencies. The compiler supplies the prelude automatically.

```text
my-project/
  Dovetail.toml
  hello/
    src/main.dove
    test/greetingTest.dove
  model/
    src/types.dove
```

To add a library, run `dovetail projects add model`, replace its generated `main`
with library declarations, and add `"model"` to the consuming project's `depends`:

```toml
compiler-version = "0.1.4"

[[project]]
name = "model"
root_package = "example.model"
packages = ["."]

[[project]]
name = "hello"
root_package = "hello"
packages = ["."]
depends = ["model"]
```

`model/src/types.dove` starts with `package example.model`. A declaration used by
`hello` must be `public` and imported there. A library has no `main`; there is no
application/library `type` field. Packages within a project are listed in dependency
order. See [Packages and Modules](https://dovetaillang.org/book/packages.md) for visibility and dependency rules.

## 2.3 Dependency Management

`compiler-version` is an exact version, not a range. The installed compiler and every
dependency manifest must agree. The compiler and its bundled prelude form one
compatibility unit.

To add standard libraries, set `standard-tag` to an **existing tag with the matching
compiler version**, then select project names through `depends`:

```toml
compiler-version = "0.1.4"
standard-tag = "<matching-tag>"

[[project]]
name = "hello"
root_package = "hello"
packages = ["."]
depends = ["standard-json", "standard-io"]
```

`<matching-tag>` is a placeholder, not a published version promise. For an arbitrary
Git library, use an explicit dependency declaration:

```toml
[[dependencies]]
git = "https://github.com/acme/libraries.git"
rev = "<full-commit-id>"
projects = ["validation"]
```

Use a repository and revision you can access; add `"validation"` to your project's
`depends` to consume it. Git selections can use a branch, tag, or revision, and
can alias selected projects. See [GitHub Dependencies](https://dovetaillang.org/book/packages.md#115-github-dependencies)
for the full syntax.

```sh
dovetail deps fetch
dovetail check --locked
dovetail deps update
dovetail check --locked --offline
```

Commit `Dovetail.toml` and the generated `Dovetail.lock`. `--locked` forbids a lockfile
change but may download the already-pinned revision. `--offline` forbids network
access and needs cached sources. Combining them requires both an unchanged lock
and sufficient local cache. Updating a dependency is deliberate work: run `deps update`,
review the lock change, and check/test consumers before committing it.

Generated sources, dependency checkouts, and caches live under `.dovetail/`.
Build artifacts live under `build/` unless overridden. Neither directory replaces
the lockfile as the reproducibility record.

## 2.4 CI and Local Compiler Development

For an installed, version-matched compiler, a minimal consumer CI sequence is:

```sh
dovetail deps fetch --locked
dovetail fmt --check
dovetail check --locked
dovetail test --locked
```

Cache `.dovetail/deps/` if useful, but retain the lockfile checks on cached builds.
This is a command sequence, not a dedicated setup action; CI must install the
compiler first.

To run a local compiler checkout against a separate workspace, enter the consumer
workspace and use Cargo's manifest option:

```sh
cargo run --manifest-path /absolute/path/to/dovetail/Cargo.toml -- check
cargo run --manifest-path /absolute/path/to/dovetail/Cargo.toml -- test
```

Cargo selects the compiler repository; Dovetail reads `Dovetail.toml` in the current
working directory. No installed executable is used.

Book maintainers can run `python3 tools/check-book.py` from the compiler checkout.
It checks local book links and runs the explicitly marked complete examples through
the local compiler. See [Book validation](https://dovetaillang.org/guides/book-validation.md) for its scope and how to
add examples.


---

# Part 3: Language Basics

Source: https://dovetaillang.org/book/language-basics/


This part covers the fundamental syntax and building blocks of Dovetail.

---

## 3.1 Layout-Sensitive Syntax

Dovetail uses indentation to define code blocks - no curly braces or semicolons needed. If you've used Python, you'll feel right at home.

### The Basics

- Use **spaces** for indentation (tabs cause a compile error)
- **Four spaces** is the formatter standard
- Code at the same indentation level belongs to the same block
- Lines can be continued by indenting more than the current block

### Where Blocks Are Used

Indented blocks appear in many places in Dovetail:

**After `=` in definitions:**

```dovetail
function greet(name: String): String =
    let message = "Hello, $name!"
    message

let result =
    let x = 10
    let y = 20
    x + y
```

**After `then` and `else` in conditionals:**

```dovetail
if x > 0 then
    debug("positive")
    x * 2
else
    debug("non-positive")
    0
```

**After `with` in match expressions:**

```dovetail
match color with
    case Red => "red"
    case Green => "green"
    case Blue => "blue"
```

**After `do` in loops:**

```dovetail
for item in list do
    debug(item)
```

**After `=>` in lambdas:**

```dovetail
let process = x =>
    let doubled = x * 2
    doubled + 1
```

### Single-Line Expressions

For short expressions, you can keep everything on one line:

```dovetail
function double(x: Int32): Int32 = x * 2

if x > 0 then x else -x
```

### Multi-Line Continuations

Lines indented more than the block continue the previous expression:

```dovetail
let result = someFunction(
    arg1,
    arg2,
    arg3)
```

### Explicit Delimiters

You can use explicit `begin`/`end` and `;` instead of relying on layout:

```dovetail
// Using layout (implicit)
function foo() =
    let x = 5
    x + 1

// Using explicit delimiters
function foo() = begin let x = 5; x + 1 end
```

### Record Construction

Record fields use semicolons as separators:

```dovetail
let point = Point { x = 10; y = 20 }
```

Or with layout:

```dovetail
let point = Point {
    x = 10
    y = 20
}
```

---

## 3.2 Comments and Documentation

### Single-Line Comments

Use `//` for regular comments:

```dovetail
// This is a comment
let x = 5  // Inline comment
```

### Documentation Comments

Use `///` for documentation comments. They support Markdown formatting:

```dovetail
/// Creates a greeting message for the given name.
///
/// Returns a friendly greeting string that can be displayed
/// to the user.
///
/// ## Example
///
/// ```
/// greet("Bob")  // "Hello, Bob!"
/// ```
function greet(name: String): String =
    "Hello, $name!"
```

Documentation comments can be attached to:
- Functions
- Types (records, enums, classes, traits)
- Type fields
- Packages (via `README.md` in package directory)

### Testing Documented Behavior

Documentation comments are displayed by tooling, but their code blocks are not
executed by `dovetail test`. Add an explicit test for documented behavior:

```dovetail
/// Adds two numbers together.
function add(a: Int32, b: Int32): Int32 = a + b

test "documented addition" = assert add(2, 3) == 5
```

The book separately checks marked complete examples in CI; see [Book validation](https://dovetaillang.org/guides/book-validation.md).
The synchronous `debug(value)` calls in examples print diagnostic output. For
application console I/O, see [the async Console API](https://dovetaillang.org/book/stdlib.md#225-io).

---

## 3.3 Variables and Bindings

### Immutable Variables (Default)

Variables are immutable by default using `let`:

```dovetail
let name = "Alice"
let age = 30

// This would be a compile error:
// name = "Bob"
```

### Mutable Variables

Use `let mutable` when you need to reassign a variable:

```dovetail
let mutable counter = 0
counter = counter + 1
counter = counter + 1
// counter is now 2
```

### Variable Shadowing

You can shadow a variable by declaring a new one with the same name:

```dovetail
let x = 5
let x = x + 1    // shadows the previous x, now x = 6
let x = "hello"  // shadows again, x is now a String
```

Shadowing creates a new variable rather than mutating the existing one.

### Type Annotations

Types are usually inferred, but you can add explicit annotations:

```dovetail
let count: Int32 = 0
let name: String = "Alice"
let ratio: Float64 = 3.14
```

---

## 3.4 Primitive Types

Dovetail provides the following primitive types:

| Type | Description |
|------|-------------|
| `Int8` | Signed 8-bit integer |
| `Int16` | Signed 16-bit integer |
| `Int32` | Signed 32-bit integer |
| `Int64` | Signed 64-bit integer |
| `Uint8` | Unsigned 8-bit integer |
| `Uint16` | Unsigned 16-bit integer |
| `Uint32` | Unsigned 32-bit integer |
| `Uint64` | Unsigned 64-bit integer |
| `Float32` | 32-bit floating point |
| `Float64` | 64-bit floating point |
| `Bool` | Boolean (`true` or `false`) |
| `Char` | Unicode character |
| `String` | UTF-8 encoded text |
| `Unit` | Empty type (like `void`) |
| `Never` | Bottom type (no values) |
| `Any` | Top type (all values) |

### Literals

```dovetail
// Integers
let decimal = 42
let hex = 0xFF
let binary = 0b1010
let octal = 0o755
let byte = 255u8       // with type suffix
let long = 1000000i64

// Floats
let pi = 3.14159
let scientific = 1.5e10
let typed = 3.14f32

// Exact numbers (available from the prelude)
let large = 123456789012345678901234567890big
let amount = 19.99dec
let exactScientific = 1.25e3dec

// Booleans
let active = true
let disabled = false

// Characters
let letter = 'A'
let emoji = '🎉'
let escaped = '\n'

// Strings
let greeting = "Hello, World!"
let multiline = """
    This is a
    multi-line string
    """

// Unit
let nothing: Unit = ()
```

`BigInt` literals use the `big` suffix and accept integer digits in any supported
base, including `0xFFbig`. `Decimal` literals use `dec` and accept base-10
integers, fractions, and scientific notation. Both are constructed exactly from
source digits, without floating-point conversion. Suffixes are lowercase and
must touch the number; digit separators are not supported.

These prelude types support `+`, `-`, `*`, unary `-`, equality, and ordering.
Operands must have the same type: write `amount * 2dec`, not `amount * 2`.
Unsuffixed literals keep their existing types, even with a `Decimal` annotation.
Literal patterns in `match` are not supported for these types; use an equality
guard instead. Division and rounding APIs are not provided yet.

Decimal uses a `BigInt` coefficient and a nonnegative `Int32` scale. Values are
normalized: `1.200dec` formats as `"1.2"`, and `-0.00dec` as `"0"`. Scientific
notation adjusts scale exactly: `1.25e3dec` is `1250dec`. Use
`Decimal.of(123big, 2)` for explicit construction, or `fromInt32`/`fromInt64`.
Negative constructor scales and arithmetic scale overflow panic. Invalid
literal scales are compile-time errors. Compiler literal construction has a
resource limit of 1,000,000 coefficient digits, including exponent expansion;
this does not limit runtime BigInt arithmetic.

`BigInt` and `Decimal` have moved from `standard.math` to `standard.prelude`;
remove their old imports. `Decimal.unscaled` and the first argument to
`Decimal.of` now use `BigInt` instead of `Int64`. `RoundingMode` remains in
`standard.math`.

### The Never Type

`Never` is special - it represents computations that never complete normally:

```dovetail
function fail(message: String): Never =
    panic message
```

It's useful for functions that always panic, unreachable code branches, and infallible async operations (`Async<T, Never>`).

### The Any Type

`Any` is the top type — every type is assignable to `Any`:

```dovetail
let a: Any = "Hello"
let b: Any = 42
let c: Any = true
```

To use a value of type `Any`, you need to test or cast it back to a concrete type using `is` and `as` (see [Type Testing and Casting](https://dovetaillang.org/book/type-system.md#610-the-any-type-and-type-casting)).

---

## 3.5 Operators

### Arithmetic Operators

| Operator | Description | Example |
|----------|-------------|---------|
| `+` | Addition | `a + b` |
| `-` | Subtraction | `a - b` |
| `*` | Multiplication | `a * b` |
| `/` | Division | `a / b` |
| `%` | Modulo | `a % b` |
| `-` | Negation (unary) | `-x` |

### Comparison Operators

| Operator | Description | Example |
|----------|-------------|---------|
| `==` | Equal | `a == b` |
| `!=` | Not equal | `a != b` |
| `<` | Less than | `a < b` |
| `<=` | Less or equal | `a <= b` |
| `>` | Greater than | `a > b` |
| `>=` | Greater or equal | `a >= b` |

### Logical Operators

Dovetail uses keywords for logical operators to improve readability:

| Operator | Description | Example |
|----------|-------------|---------|
| `and` | Logical AND | `a and b` |
| `or` | Logical OR | `a or b` |
| `not` | Logical NOT | `not x` |

Short-circuit evaluation applies: `and` stops if the left side is false, `or` stops if the left side is true.

### Bitwise Operators

| Operator | Description | Example |
|----------|-------------|---------|
| `&` | Bitwise AND | `a & b` |
| `\|` | Bitwise OR | `a \| b` |
| `^` | Bitwise XOR | `a ^ b` |
| `~` | Bitwise NOT | `~x` |
| `<<` | Left shift | `a << 2` |
| `>>` | Right shift | `a >> 2` |

### Sequence Operators

| Operator | Description | Example |
|----------|-------------|---------|
| `::` | Prepend one element to a list | `x :: xs` |
| `++` | Join two sequences | `xs ++ ys` |

`::` is right-associative, so `1 :: 2 :: rest` prepends both in order. `++`
concatenates; it works on `String` natively and on any type implementing the
`Concat` trait, including `List`.

```dovetail
let xs = 1 :: [2, 3]        // [1, 2, 3]
let ys = [1, 2] ++ [3, 4]   // [1, 2, 3, 4]
```

### Operator Precedence

From lowest to highest:

1. `or` (logical or)
2. `and` (logical and)
3. binary `~` ([tuple extension, advanced](https://dovetaillang.org/book/tuple-extension.md))
4. `==`, `!=` (equality)
5. `<`, `<=`, `>`, `>=` (comparison)
6. `::` (cons — **right**-associative)
7. `|` (bitwise or)
8. `^` (bitwise xor)
9. `&` (bitwise and)
10. `<<`, `>>` (shift)
11. `+`, `-`, `++` (additive and concatenation)
12. `*`, `/`, `%` (multiplicative)
13. `not`, `-`, `~` (unary prefix)
14. Function calls, field access, indexing, `is`, `as` (postfix)

So `x :: xs ++ ys` groups as `x :: (xs ++ ys)`, and `x :: xs == ys` as
`(x :: xs) == ys`.

Use parentheses when precedence is unclear:

```dovetail
let result = (a + b) * c
let check = (x > 0) and (y < 10)
```

---

## 3.6 String Interpolation

Dovetail supports string interpolation in all strings - no special prefix needed.

### Simple Variable Interpolation

Use `$` followed by a variable name:

```dovetail
let name = "Alice"
let greeting = "Hello, $name!"  // "Hello, Alice!"
```

### Expression Interpolation

Use `${}` for complex expressions:

```dovetail
let x = 10
let y = 20
let message = "Sum: ${x + y}"  // "Sum: 30"

let user = getUser()
let info = "User ${user.name} is ${user.age} years old"
```

### Escape Sequences

| Sequence | Meaning |
|----------|---------|
| `\n` | Newline |
| `\r` | Carriage return |
| `\t` | Tab |
| `\\` | Backslash |
| `\"` | Double quote |
| `\$` | Literal dollar sign |
| `\0` | Null character |
| `\u{XXXX}` | Unicode code point |

```dovetail
let escaped = "Line 1\nLine 2"
let price = "Cost: \$99.99"  // Literal $, not interpolation
let heart = "\u{2764}"       // ❤
```

### Prefixed Literals

A string may carry an identifier on its opening quote — `sql"SELECT * FROM t WHERE id = $id"`. The prefix hands the literal to a library, which decides what interpolation means: in a `sql"..."` literal, `$id` binds a parameter rather than splicing text. Prefixed literals also add a spread form, `$..values`, which exists nowhere else. See [Part 24](https://dovetaillang.org/book/prefixed-literals.md).

### Multi-line Strings

Use triple quotes for multi-line strings:

```dovetail
let poem = """
    Roses are red,
    Violets are blue,
    Dovetail is great,
    And so are you!
    """
```

Interpolation works in multi-line strings too:

```dovetail
let name = "World"
let html = """
    <html>
      <body>
        <h1>Hello, $name!</h1>
      </body>
    </html>
    """
```

### String Concatenation

Use `++` to concatenate strings:

```dovetail
let first = "Hello"
let second = "World"
let combined = first ++ ", " ++ second ++ "!"
```

For building strings dynamically, consider using `StringBuilder` from the standard library for better performance.

---

## Summary

You now understand Dovetail's basic syntax:

- **Layout-sensitive** - Indentation defines blocks, no braces or semicolons needed
- **Comments** - `//` for regular, `///` for documentation with Markdown
- **Variables** - Immutable by default (`let`), use `let mutable` for mutation
- **Primitive types** - Integers, floats, booleans, characters, strings, unit, never, any
- **Operators** - Standard arithmetic/comparison, keywords for logical (`and`, `or`, `not`)
- **String interpolation** - `$variable` and `${expression}` in any string

In the next part, we'll explore control flow with if expressions, pattern matching, and loops.


---

# Part 4: Control Flow

Source: https://dovetaillang.org/book/control-flow/


This part covers how to control the flow of execution in Dovetail programs.

---

## 4.1 If Expressions

In Dovetail, `if` is an expression - it always returns a value. This makes it more powerful than traditional if statements.

### Basic Syntax

```dovetail
if condition then
    expression1
else
    expression2
```

### Examples

**Simple if/else:**

```dovetail
let max = if a > b then a else b
```

**Multi-line blocks:**

```dovetail
let result = if user.isActive then
    debug("User is active")
    user.score * 2
else
    debug("User is inactive")
    0
```

**Single-line form:**

```dovetail
let sign = if x > 0 then "positive" else "non-positive"
```

### Else If Chains

Use `else if` for multiple conditions:

```dovetail
let grade = if score >= 90 then
    "A"
else if score >= 80 then
    "B"
else if score >= 70 then
    "C"
else if score >= 60 then
    "D"
else
    "F"
```

### If Without Else

When you don't need a value, you can omit `else`. The expression returns `Unit`:

```dovetail
if shouldLog then
    debug("Logging enabled")
```

### Nested If

If expressions can be nested:

```dovetail
let category = if age < 13 then
    "child"
else
    if age < 20 then "teenager" else "adult"
```

But prefer `else if` chains or `match` for better readability.

---

## 4.2 Match Expressions

`match` is Dovetail's powerful pattern matching construct. It's like `switch` in other languages, but much more expressive.

### Basic Syntax

```dovetail
match value with
    case pattern1 => result1
    case pattern2 => result2
    case _ => defaultResult
```

### Matching Literals

```dovetail
let dayName = match dayNumber with
    case 1 => "Monday"
    case 2 => "Tuesday"
    case 3 => "Wednesday"
    case 4 => "Thursday"
    case 5 => "Friday"
    case 6 => "Saturday"
    case 7 => "Sunday"
    case _ => "Invalid day"
```

### Matching Enums

Pattern matching shines with enums:

```dovetail
enum Color =
    Red
    Green
    Blue
    RGB(Uint8, Uint8, Uint8)

let description = match color with
    case Red => "Pure red"
    case Green => "Pure green"
    case Blue => "Pure blue"
    case RGB(r, g, b) => "RGB($r, $g, $b)"
```

### Matching Option

```dovetail
let message = match maybeUser with
    case Some(user) => "Hello, ${user.name}!"
    case None => "Hello, guest!"
```

### Matching Result

```dovetail
match fetchData() with
    case Ok(data) => processData(data)
    case Error(err) => debug("Error: $err")
```

### Destructuring Records

```dovetail
record Point =
    x: Int32
    y: Int32

let quadrant = match point with
    case Point { x; y } if x > 0 and y > 0 => "Q1"
    case Point { x; y } if x < 0 and y > 0 => "Q2"
    case Point { x; y } if x < 0 and y < 0 => "Q3"
    case Point { x; y } if x > 0 and y < 0 => "Q4"
    case _ => "Origin or on axis"
```

Commas are also accepted between record-pattern fields, but `dovetail fmt`
normalizes them to semicolons. In a multiline pattern, semicolons appear
between fields but not after the last field.

### Matching Tuples

```dovetail
let description = match (x, y) with
    case (0, 0) => "Origin"
    case (0, _) => "On Y axis"
    case (_, 0) => "On X axis"
    case (a, b) if a == b => "On diagonal"
    case _ => "Somewhere else"
```

### Matching Lists

A list matches either as a fixed set of elements or as a head and a tail:

```dovetail
let description = match xs with
    case [] => "empty"
    case [only] => "exactly one"
    case [a, b] => "exactly two"
    case h :: t => "at least one more"
```

`h :: t` binds `h` to the first element and `t` to the rest, which makes
recursion over a list read directly:

```dovetail
function sum(xs: List<Int32>): Int32 =
    match xs with
        case [] => 0
        case h :: t => h + sum(t)
```

`[]` and `h :: t` together cover every list, so the pair needs no wildcard:

```dovetail
let first = match xs with
    case [] => "none"
    case h :: t => h.format()
```

Fixed-length patterns do **not** cover everything, though — `case []` plus
`case [a, b]` leaves a one-element list unmatched, and the compiler says so:

```
non-exhaustive match: missing case for [_]
```

These patterns match a `List` only. Arrays have no pattern form; index them or
iterate them instead.

### Guard Conditions

Add `if` after a pattern for additional conditions:

```dovetail
let category = match age with
    case n if n < 0 => "Invalid"
    case n if n < 13 => "Child"
    case n if n < 20 => "Teenager"
    case n if n < 65 => "Adult"
    case _ => "Senior"
```

### The Wildcard Pattern

Use `_` to match anything you don't care about:

```dovetail
match triple with
    case (first, _, _) => first  // Only care about first element
```

### Variable Binding

Patterns can bind values to names:

```dovetail
match result with
    case Ok(value) => debug("Got: $value")
    case Error(e) => debug("Error: $e")
```

### Exhaustiveness

The compiler ensures all cases are covered. This won't compile:

```dovetail
enum Direction = North | South | East | West

// Error: non-exhaustive match
let name = match dir with
    case North => "N"
    case South => "S"
    // Missing East and West!
```

Use `_` as a catch-all if needed:

```dovetail
let name = match dir with
    case North => "N"
    case South => "S"
    case _ => "Other"
```

---

## 4.3 Loops

Dovetail provides `for` and `while` loops for iteration.

### For Loops

Iterate over a value that implements `Iterable<T>`, including arrays, lists, slices, and collection ranges:

```dovetail
for item in list do
    debug(item)
```

**Over a slice:**

```dovetail
let values = [|10, 20, 30, 40|]
let mutable total = 0
for value in values[|1..3|] do
    total = total + value
assert total == 50
```

See [Lists, Arrays, and Slices](https://dovetaillang.org/book/type-system.md#67-lists-arrays-and-slices) for slicing forms and shared-mutation behavior. The `..` notation is only valid inside slicing brackets; use the collection `Range` API for a numeric loop.

**With index using enumerate:**

```dovetail
for (index, item) in list.zipWithIndex() do
    debug("$index: $item")
```

**Over a range:**

```dovetail
for i in Range.new(0, 10) do
    debug(i)  // 0 to 9

for i in Range.inclusive(0, 10) do
    debug(i)  // 0 to 10 (inclusive)
```

**Iterating over maps:**

```dovetail
for (key, value) in map do
    debug("$key -> $value")
```

### While Loops

Execute while a condition is true:

```dovetail
let mutable count = 0
while count < 10 do
    debug(count)
    count = count + 1
```

### Loop as Expression

Loops return `Unit`:

```dovetail
let result: Unit = for i in [|0, 1, 2, 3, 4|] do
    debug(i)
```

### Early Exit

Use `break` to exit a loop early:

```dovetail
let mutable found = false
for item in list do
    if item == target then
        found = true
        break
```

Use `continue` to skip to the next iteration:

```dovetail
for item in list do
    if item < 0 then
        continue  // Skip negative numbers
    debug(item)
```

### Functional Alternatives

For many use cases, functional methods are cleaner than loops:

```dovetail
// Instead of a loop to transform
let doubled = numbers.map(x => x * 2)

// Instead of a loop to filter
let positive = numbers.filter(x => x > 0)

// Instead of a loop to sum
let total = numbers.fold(0, (acc, x) => acc + x)

// Instead of a loop to find
let found = numbers.find(x => x > 100)
```

These functional approaches are often more readable and eliminate the need for mutable variables.

---

## Summary

Dovetail provides expressive control flow constructs:

- **If expressions** - Always return a value, can be used anywhere an expression is expected
- **Match expressions** - Powerful pattern matching with destructuring, guards, and exhaustiveness checking
- **Loops** - `for` and `while` for iteration, with `break` and `continue` for control

A key principle: prefer pattern matching over long if/else chains, and prefer functional methods (`map`, `filter`, `fold`) over imperative loops when it makes the code clearer.

In the next part, we'll explore functions in depth.

For restrictions on loops that suspend, see [Async Programming](https://dovetaillang.org/book/async.md).


---

# Part 5: Functions

Source: https://dovetaillang.org/book/functions/


Functions are the primary building blocks in Dovetail. They are first-class values, meaning you can pass them around, return them from other functions, and store them in variables.

---

## 5.1 Function Definitions

### Basic Syntax

Functions are defined using the `function` keyword:

```dovetail
function greet(): String =
    "Hello, World!"
```

The function body follows the `=` sign. Since Dovetail is expression-based, the last expression in the body is the return value.

### Parameters and Return Types

Functions can take parameters with type annotations. The return type follows the parameter list:

```dovetail
function add(a: Int32, b: Int32): Int32 =
    a + b

function formatUser(name: String, age: Int32): String =
    "$name is $age years old"
```

### Unit Return Type

Functions that don't return a meaningful value return `Unit`:

```dovetail
function greet(name: String): Unit =
    debug("Hello, $name!")
```

You can omit the return type annotation for `Unit`:

```dovetail
function greet(name: String) =
    debug("Hello, $name!")
```

### Multi-Line Function Bodies

Function bodies can span multiple lines. Each line is an expression, and the last expression is returned:

```dovetail
function calculateTotal(price: Float64, quantity: Int32): Float64 =
    let subtotal = price * quantity.toFloat64()
    let tax = subtotal * 0.08
    subtotal + tax
```

### Visibility

Top-level functions default to `internal` (package visibility). Use `public` to
make them accessible from other packages, or `private` for file-local helpers:

```dovetail
public function add(a: Int32, b: Int32): Int32 =
    a + b
```

---

## 5.2 Named and Default Arguments

### Named Arguments

When calling a function, you can use named arguments for clarity:

```dovetail
function createUser(name: String, age: Int32, email: String): User =
    User { name = name; age = age; email = email }

// Using named arguments
let user = createUser(name = "Alice", age = 30, email = "alice@example.com")
```

Named arguments can be in any order:

```dovetail
let user = createUser(email = "bob@example.com", name = "Bob", age = 25)
```

You can mix positional and named arguments, but positional arguments must come first:

```dovetail
let user = createUser("Charlie", age = 28, email = "charlie@example.com")
```

Every parameter must receive exactly one argument. Unknown names, duplicate
arguments (including a positional and named argument for the same parameter),
missing arguments, and positional arguments after named ones are errors.

Named arguments also work with methods and class constructors. The receiver is
evaluated first, then eager arguments are evaluated once in the order written,
even when that differs from parameter order. `ByName` arguments remain deferred.

Accepted names come from the declaration visible at the call site. Calls through
a trait bound or interface use that contract's names; calls through a base class
use its visible method declaration. Calls through a concrete class use its own
method declaration, or the inherited declaration when it does not override the
method. An implementation may rename parameters, but those names are not aliases
for the contract's names. Runtime dispatch does not affect argument binding.
Renaming a public parameter can therefore break callers that use its name.

Function values, including stored function and bound-method references, accept
only positional arguments: their types do not contain parameter names. Positional
enum payloads and newtype constructors also have no argument labels. Record
construction continues to use its existing field-initializer syntax.

### Default Parameter Values (Planned)

Default parameter values are planned but are not implemented yet. For optional
settings today, use a configuration record and a function that constructs it:

```dovetail
record Config =
    host: String
    port: Int32

function defaultConfig(host: String): Config =
    Config { host = host; port = 8080 }

let local = defaultConfig("localhost")
let custom = local with { port = 3000 }
```

Record field assignments are distinct from function arguments. The formatter
preserves that distinction; it does not introduce named arguments.

The proposed default-parameter syntax is:

```dovetail
function greet(name: String, greeting: String = "Hello"): String =
    "$greeting, $name!"

greet("Alice")           // "Hello, Alice!"
greet("Bob", "Hi")       // "Hi, Bob!"
greet("Charlie", greeting = "Hey")  // "Hey, Charlie!"
```

Parameters with defaults must come after required parameters:

```dovetail
function createConfig(
    host: String,
    port: Int32 = 8080,
    timeout: Int32 = 30,
    debug: Bool = false
): Config =
    Config { host = host; port = port; timeout = timeout; debug = debug }

// Use defaults
let config1 = createConfig("localhost")

// Override some defaults
let config2 = createConfig("localhost", port = 3000, debug = true)
```

### Future Linter Rule for Named Arguments

The formatter preserves the caller's choice of positional or named arguments.
Adding argument names requires resolving the called declaration and belongs in
a semantic linter.

Dovetail does not yet have a linter. A planned rule would suggest named arguments
when the called declaration has more than two explicit parameters, excluding
the method receiver:

```dovetail
// You write:
createUser("John", 30, "john@example.com")

// A future linter could suggest this fix:
createUser(name = "John", age = 30, email = "john@example.com")
```

Additional planned lint rules require named arguments for Boolean and numeric
literals, even in calls with only one or two parameters. For example,
`retry(3)` would be written as `retry(attempts = 3)`. These lint rules are not
implemented yet. See the [future linter design and rule backlog](https://github.com/somdoron/dovetail/blob/main/docs/linter-design.md).

---

## 5.3 Closures and Lambdas

### Basic Closure Syntax

Closures (anonymous functions) use the `=>` arrow:

```dovetail
// With type annotations (via expected type)
let multiply: (Int32, Int32) => Int32 = (a, b) => a * b

// Single parameter - no parentheses needed
let double = (x: Int32) => x * 2

// Multiple parameters - parentheses required
let add = (a: Int32, b: Int32) => a + b
```

### Multi-Line Closures

Closure bodies can span multiple lines using indentation:

```dovetail
let process = (x: Int32) =>
    let y = x + 1
    let z = y * 2
    z + 10
```

### Environment Capture

Closures can capture variables from their surrounding scope:

```dovetail
let multiplier = 3
let scale = (x: Int32) => x * multiplier

scale(5)  // 15
```

Closures capture variables by reference:

```dovetail
function makeCounter(): () => Int32 =
    let mutable count = 0
    () =>
        count = count + 1
        count

let counter = makeCounter()
counter()  // 1
counter()  // 2
counter()  // 3
```

### Function Types

Function types describe the signature of a function:

```dovetail
// A function that takes two Int32s and returns an Int32
let operation: (Int32, Int32) => Int32 = (a, b) => a + b

// A function that takes no arguments and returns Unit
let action: () => Unit = () => debug("Hello!")

// A function that takes a String and returns a Bool
let predicate: (String) => Bool = s => s.length > 0
```

---

## 5.4 First-Class Function References

Named functions can be used as values wherever a function type is expected. Simply use the function name without calling it:

```dovetail
function double(x: Int32): Int32 = x * 2

let f: Int32 => Int32 = double
f(5)  // 10
```

### Passing Functions as Arguments

```dovetail
function identity(x: Int32): Int32 = x

function apply(f: Int32 => Int32, value: Int32): Int32 = f(value)

apply(identity, 42)  // 42
```

### Module Functions

Module functions work the same way:

```dovetail
module Math =
    function square(x: Int32): Int32 = x * x

let f: Int32 => Int32 = Math.square
f(4)  // 16
```

### Generic Functions

Generic functions can be used as values when the expected type provides enough information to instantiate the type parameters:

```dovetail
function identity<T>(x: T): T = x

let f: Int32 => Int32 = identity  // T inferred as Int32
f(42)  // 42
```

### Overload Disambiguation

When multiple overloads exist, the expected type disambiguates:

```dovetail
function convert(x: Int32): String = "$x"
function convert(x: String): Int32 = 0

let f: Int32 => String = convert  // selects first overload
```

---

## 5.5 Method References

### Bound Method References

When you access a method on an instance without calling it, you get a **bound method reference** — a function value with `self` already captured:

```dovetail
record Point =
    x: Int32
    y: Int32

module Point =
    function getX(self): Int32 = self.x
    function addX(self, dx: Int32): Int32 = self.x + dx

let p = Point { x = 42; y = 0 }

// Bound reference — self (p) is captured
let f = p.getX       // type: Unit => Int32
f()                   // 42

let g = p.addX        // type: Int32 => Int32
g(10)                 // 52
```

The resulting function type excludes `self` from the parameter list since it is already bound to the object.

### Unbound Method References

You can also reference a method via the type name. This produces a function that takes `self` as its first parameter:

```dovetail
let f: Point => Int32 = Point.getX
let p = Point { x = 42; y = 0 }
f(p)  // 42
```

### Class Methods

Method references work with class instance methods too:

```dovetail
class Counter(public value: Int32) =
    public function getValue(self: Counter): Int32 = self.value

let c = Counter(99)
let f = c.getValue
f()  // 99
```

### Using Method References with Higher-Order Functions

Method references are especially useful when passing to higher-order functions:

```dovetail
function apply(f: Int32 => Int32, arg: Int32): Int32 = f(arg)

let p = Point { x = 42; y = 0 }
apply(p.addX, 10)  // 52
```

---

## 5.6 Higher-Order Functions

Higher-order functions are functions that take other functions as parameters or return functions.

### Functions as Parameters

```dovetail
function applyTwice(f: (Int32) => Int32, x: Int32): Int32 =
    f(f(x))

let double = (x: Int32) => x * 2
applyTwice(double, 5)  // 20 (5 * 2 * 2)
```

### Common Higher-Order Functions

Dovetail's standard library provides common higher-order functions for collections:

**map** - Transform each element:

```dovetail
let numbers = [1, 2, 3, 4, 5]
let doubled = numbers.map(x => x * 2)  // [2, 4, 6, 8, 10]
```

**filter** - Keep elements matching a predicate:

```dovetail
let numbers = [1, 2, 3, 4, 5]
let evens = numbers.filter(x => x % 2 == 0)  // [2, 4]
```

**foldLeft** - Reduce to a single value:

```dovetail
let numbers = [1, 2, 3, 4, 5]
let sum = numbers.foldLeft(0, (acc, x) => acc + x)  // 15
```

### Returning Functions

Functions can return other functions:

```dovetail
function makeMultiplier(factor: Int32): (Int32) => Int32 =
    x => x * factor

let triple = makeMultiplier(3)
triple(7)  // 21
```

### Pipeline Style

Higher-order functions enable a clean pipeline style:

```dovetail
let result = numbers
    .filter(x => x > 0)
    .map(x => x * 2)
    .foldLeft(0, (acc, x) => acc + x)
```

This style is often more readable than nested function calls:

```dovetail
// Equivalent but harder to read
let result = numbers.filter(x => x > 0).map(x => x * 2).foldLeft(0, (acc, x) => acc + x)
```

---

## Summary

- Functions are defined with `function name(params): ReturnType = body`
- Use named arguments for clarity: `createUser(name = "Alice", age = 30)`
- Default parameter values are planned; use configuration records for defaults today
- Closures use `=>` syntax: `x => x * 2` or `(a, b) => a + b`
- Closures capture variables from their environment
- Function types describe signatures: `(Int32, Int32) => Int32`
- Named functions can be used as values: `let f: Int32 => Int32 = double`
- Bound method references capture self: `let f = point.getX`
- Unbound method references include self: `let f: Point => Int32 = Point.getX`
- Higher-order functions take or return other functions
- Use `map`, `filter`, and `foldLeft` for collection processing


---

# Part 6: Type System

Source: https://dovetaillang.org/book/type-system/


Dovetail has a powerful type system that catches errors at compile time while keeping your code clean through type inference.

---

## 6.1 Type Inference

Dovetail infers types whenever possible, so you don't need to write them explicitly:

```dovetail
let name = "Alice"        // inferred as String
let age = 30              // inferred as Int32
let price = 19.99         // inferred as Float64
let active = true         // inferred as Bool
```

You can add explicit type annotations when needed:

```dovetail
let count: Int64 = 100    // explicitly Int64, not Int32
let ratio: Float32 = 0.5  // explicitly Float32, not Float64
```

Function return types must be explicit (for readability), except for `Unit`:

```dovetail
function double(x: Int32): Int32 = x * 2

function calculateTotal(price: Float64, quantity: Int32): Float64 =
    price * quantity.toFloat64()

// Unit return type can be omitted
function greet(name: String) =
    debug("Hello, $name!")
```

---

## 6.2 Records

Records are data-only types with named fields. They're similar to structs in other languages.

### Defining Records

```dovetail
record Point =
    x: Int32
    y: Int32

record User =
    name: String
    email: String
    age: Int32
```

### Creating Records

Use the record name followed by field initializers in braces:

```dovetail
let origin = Point { x = 0; y = 0 }
let user = User { name = "Alice"; email = "alice@example.com"; age = 30 }
```

Multi-line syntax:

```dovetail
let user = User {
    name = "Alice"
    email = "alice@example.com"
    age = 30
}
```

### Accessing Fields

Use dot notation:

```dovetail
let userName = user.name
let userAge = user.age
```

### Updating Records with `with`

Records are immutable. Use `with` to create a modified copy:

```dovetail
let older = user with { age = user.age + 1 }
let renamed = user with { name = "Bob" }
```

### Private Construction

Put `private` after the record name to reserve construction and `with` updates for its associated module:

```dovetail
public record Account private =
    balance: Int32

module Account =
    public function make(balance: Int32): Result<Account, String> =
        if balance < 0 then Error("balance must not be negative")
        else Ok(Account { balance = balance })

    public function deposit(self, amount: Int32): Result<Account, String> =
        if amount < 0 then Error("deposit must not be negative")
        else Ok(self with { balance = self.balance + amount })
```

Any caller that can see `Account` can read `account.balance` and destructure an account in a pattern. Only `module Account` in the defining package can write `Account { ... }` or `account with ...`. Sharing the package or file is not enough; trait implementations and extensions must call the module's functions too.

Leading `public` controls visibility of the type itself. For generic records, write `record Box<T> private where T: Equatable = ...`: the construction modifier follows type parameters and precedes constraints. Empty private records use `record Token private`, with the modifier on the same line as the name.

### Records are Equatable

Records with equatable fields can opt into equality with `@derive(Equatable)`
on the record declaration:

```dovetail
@derive(Equatable)
record Point =
    x: Int32
    y: Int32

let p1 = Point { x = 1; y = 2 }
let p2 = Point { x = 1; y = 2 }
p1 == p2  // true
```

---

## 6.3 Enums (Discriminated Unions)

Enums represent values that can be one of several variants. Each variant can optionally carry data.

### Simple Enums

```dovetail
enum Color =
    Red
    Green
    Blue

let color = Red
```

### Enums with Data

Variants can carry payload data:

```dovetail
enum Shape =
    Circle(Float64)           // radius
    Rectangle(Float64, Float64)  // width, height
    Point

let circle = Circle(5.0)
let rect = Rectangle(10.0, 20.0)
let point = Point
```

### Pattern Matching on Enums

Use `match` to handle different variants:

```dovetail
function area(shape: Shape): Float64 =
    match shape with
        case Circle(radius) => 3.14159 * radius * radius
        case Rectangle(w, h) => w * h
        case Point => 0.0
```

### Named Record Payloads

A variant with exactly one record payload supports both positional and record syntax:

```dovetail
record Placement =
    placedAt: Int32
    total: Int32

enum OrderStatus =
    Draft
    Placed(Placement)

let placement = Placement { placedAt = 1; total = 100 }
let first = OrderStatus.Placed(placement)
let second = OrderStatus.Placed { placedAt = 1; total = 100 }
```

The brace construction is shorthand for `OrderStatus.Placed(Placement { placedAt = 1; total = 100 })`. The payload remains a `Placement` value that can be passed around independently.

Patterns can bind that whole value or inspect its fields:

```dovetail
function total(status: OrderStatus): Int32 =
    match status with
        case Placed { total } => total
        case Draft => 0
```

`case Placed { total }` means `case Placed(Placement { total })`; `case Placed(placement)` binds the whole record. Ordinary record pattern rules apply, including omitted fields and nested patterns. Extracting an inline record variant into a named payload can therefore preserve its brace construction and patterns.

Braces unwrap exactly one record payload. They do not unwrap newtypes, classes, or multiple positional payloads. Generic payloads work when their record type is known: `Some { total = 100; placedAt = 1 }` needs an expected type such as `Option<Placement>`. Fields alone do not identify a nominal record type. Custom construction uses the enum qualifier; patterns can infer it from the matched value.

Construction checks both the enum's and the payload record's construction permissions. A private record constructor does not prevent inspecting its public fields through a variant pattern or wrapping an existing record value in a publicly constructible enum.

### Private Construction of Enums

The same modifier reserves every variant's construction for the enum's associated module:

```dovetail
public enum Status private =
    Open
    Closed

module Status =
    public function open(): Status = Status.Open
    public function close(self): Status = Status.Closed

function isClosed(status: Status): Bool =
    match status with
        case Status.Open => false
        case Status.Closed => true
```

Outside `module Status`, `Status.Open` is allowed in a pattern but rejected as a value expression, because that would construct a value. This applies to variants with no payload, tuple payloads, and named record payloads. Patterns still expose their payloads, and exhaustiveness checking is unchanged. The `with` expression remains a record operation; this does not add enum updates.

### Option Type

The prelude's `Option<T>` type represents optional values. It is available without an import:

```dovetail
enum Option<T> =
    Some(T)
    None

function findUser(id: Int32): Option<User> =
    if id == 1 then
        Some(User { name = "Alice"; email = "a@b.com"; age = 30 })
    else
        None
```

See [Option Type in chapter 10](https://dovetaillang.org/book/error-handling.md#102-option-type) for its methods and guidance on handling missing values.

### Result Type

The prelude's `Result<T, E>` type represents success or failure. It is also available without an import:

```dovetail
enum Result<+T, +E> =
    Ok(T)
    Error(E)

function divide(a: Int32, b: Int32): Result<Int32, String> =
    if b == 0 then
        Error("Division by zero")
    else
        Ok(a / b)
```

See [Result Type in chapter 10](https://dovetaillang.org/book/error-handling.md#103-result-type) for its methods and [the `try` expression](https://dovetaillang.org/book/error-handling.md#try-and-orreturn) for propagating failures.

---

## 6.4 Tuples

Tuples group multiple values of different types.

### Creating Tuples

```dovetail
let pair = (1, "hello")
let triple = (10, 20.5, true)
```

### Accessing Tuple Elements

Use pattern matching or numbered accessors:

```dovetail
let (x, y) = pair
// x is 1, y is "hello"

let first = triple._0   // 10
let second = triple._1  // 20.5
```

### Tuples vs Records

- Use tuples for quick grouping of a few values
- Use records when you need meaningful field names
- Records are better for public APIs

For generic tuple construction, shape constraints, and implementations across
tuple arities, see [Part 25: Tuple Extension (Advanced)](https://dovetaillang.org/book/tuple-extension.md).

---

## 6.5 Newtypes

Newtypes create distinct types from existing types, preventing accidental mixing.

### Defining Newtypes

```dovetail
newtype UserId = Int32
newtype OrderId = Int32
newtype Email = String
```

### Using Newtypes

```dovetail
let userId = UserId(123)
let orderId = OrderId(456)

// This won't compile - different types!
// let wrong: UserId = orderId  // Error!
```

### Why Newtypes?

Newtypes prevent bugs by making the type system work for you:

```dovetail
function getUser(id: UserId): Option<User> = ...
function getOrder(id: OrderId): Option<Order> = ...

let userId = UserId(123)
let orderId = OrderId(456)

getUser(userId)   // OK
getUser(orderId)  // Compile error! Can't pass OrderId where UserId expected
```

### Private Newtypes

A private newtype reserves both construction and inspection for its associated module:

```dovetail
public newtype Password private = String

module Password =
    public function parse(value: String): Result<Password, String> =
        if value.length < 8 then
            Error("Password must be at least 8 characters")
        else
            Ok(Password(value))

    public function matches(self, other: String): Bool =
        self.value == other
```

Only `module Password` in the defining package may call `Password(...)`, access `.value`, or unwrap a `Password(value)` pattern. Other code can store, pass, and compare passwords and call the module's public functions. Trait implementations and extensions have no special access, even in the same package.

Private records and enums expose their fields and patterns; private newtypes keep the wrapped value opaque. All three use `Name<T> private where ... = ...`, but their inspection rules differ. The old `newtype Name = private Type` syntax is rejected.

---

## 6.6 Type Aliases

Type aliases create alternative names for existing types. Unlike newtypes, they're interchangeable with the original type.

### Defining Type Aliases

```dovetail
type Name = String
type Age = Int32
type Coordinate = (Int32, Int32)
type UserMap = Map<UserId, User>
```

### Using Type Aliases

```dovetail
function greet(name: Name): String =
    "Hello, $name!"

let name: Name = "Alice"
greet(name)    // OK
greet("Bob")   // Also OK - Name is just String
```

### When to Use Type Aliases vs Newtypes

- **Type aliases**: For convenience and readability (great for tuples and function types)
- **Newtypes**: When you need type safety and distinction

```dovetail
// Type aliases make complex types readable
type Coordinate = (Int32, Int32)
type Handler = (Request) => Response
type Callback<T> = (T) => Unit

// Newtypes create distinct types
newtype UserId = Int32
newtype OrderId = Int32
```

---

## 6.7 Lists, Arrays, and Slices

`List<T>`, `Array<T>`, and `Slice<T>` are available from the prelude without imports. Lists are immutable linked sequences; arrays are fixed-size mutable collections; slices are writable views into arrays.

### Lists and List Literals

Square brackets create a `List<T>`. The element type is inferred from the contents or the surrounding context:

```dovetail
let numbers: List<Int32> = [1, 2, 3]
let names = ["Alice", "Bob"]
let empty: List<Int32> = []
let nested: List<List<Int32>> = [[1, 2], [3]]
assert numbers.length == 3
assert empty.isEmpty
```

A list is an immutable singly linked sequence, defined as `List<out T> = Nil | Cons(T, List<T>)` in the prelude and used as the standard library's default sequence type. It is represented by the enum variants `Nil` (empty) and `Cons(head, tail)`. `[]` is the literal spelling of `Nil`; `[1, 2]` is equivalent to `Cons(1, Cons(2, Nil))`. `List.empty` also creates an empty list.

Use `::` to prepend an element or `++` to concatenate lists. These operations leave the original lists unchanged. Prepending shares the existing tail and takes constant time; concatenation copies the left list's nodes and takes time proportional to its length. `::` associates to the right:

```dovetail
let original = [2, 3]
let extended = 1 :: original
assert extended == [1, 2, 3]
assert original == [2, 3]
assert 1 :: 2 :: [] == [1, 2]
assert [1, 2] ++ [3, 4] == [1, 2, 3, 4]
```

`List` is covariant (`out T`), so an empty list fits wherever a `List<T>` is expected without an annotation at the call site:

```dovetail
function total(xs: List<Int32>): Int32 = xs.foldLeft(0, (a, b) => a + b)
total([])
```

`::` binds looser than `+` and `++`, and tighter than comparison — so `x :: xs ++ ys` is `x :: (xs ++ ys)`, and `x :: xs == ys` is `(x :: xs) == ys`.

The list structure is immutable; objects stored as elements may still have mutable state.

### Accessing and Matching Lists

`head` and `tail` return the first element and the remaining list, and panic on an empty list. `headOption` and `get(index)` return `Option<T>` instead; `get` returns `None` for a negative or out-of-bounds index. Lists use `.get(i)` for indexed lookup. Both indexed lookup and `length` traverse the list, so use an array when frequent random access matters.

```dovetail
let numbers = [10, 20, 30]
assert numbers.head == 10
assert numbers.tail == [20, 30]
assert numbers.headOption.or(0) == 10
assert numbers.get(1).or(0) == 20
assert numbers.get(3).isNone
```

Patterns can match an empty list, an exact number of elements, or a head and tail:

```dovetail
function describeList(values: List<Int32>): String =
    match values with
        case [] => "empty"
        case [only] => "one element"
        case first :: rest => "multiple elements"
```

### Transforming and Iterating Lists

`map`, `filter`, `take`, `drop`, and `reverse` return lists without changing the original. `foldLeft` combines the elements into a single value. `toArray()` copies the elements into a new mutable array:

```dovetail
let numbers = [1, 2, 3]
assert numbers.map(x => x * 2) == [2, 4, 6]
assert numbers.filter(x => x > 1) == [2, 3]
assert numbers.take(2) == [1, 2]
assert numbers.drop(1) == [2, 3]
assert numbers.reverse() == [3, 2, 1]
assert numbers.find(n => n > 1) == Some(2)
assert numbers.contains(2)
assert numbers.foldLeft(0, (total: Int32, value: Int32) => total + value) == 6
let array = numbers.toArray()
array[0] = 99
assert numbers.head == 1

let mutable sum = 0
for number in numbers do
    sum = sum + number
assert sum == 6
```

Lists compare by contents with `==` and `!=` when their elements implement `Equatable`. They compare lexicographically when their elements implement `Comparable`.

### Choosing Between Array and List

|  | `List<T>` | `Array<T>` |
|---|---|---|
| Literal | `[1, 2]` | `[\| 1, 2 \|]` |
| Prepend | O(1) | O(n) |
| Index / length | O(n) | O(1) |
| Mutable | no | yes |
| Variance | covariant (`out T`) | invariant |
| Pattern matching | yes | no |

Reach for a **list** when you build a sequence once and read it front to back,
which is most business logic. Reach for an **array** when you index it, mutate
it, know its size up front, or are holding bytes.

### Creating Arrays

Arrays are fixed-size, mutable, indexed collections. Array literals use `[| ... |]`; list literals use `[ ... ]`:

```dovetail
let numbers = [| 1, 2, 3, 4, 5 |]
let names = [| "Alice", "Bob", "Charlie" |]
let empty: Array<Int32> = [||]
```

The plain `[ ... ]` form is a *list* literal (§6.7). Arrays get the marked
syntax because they are the specialised choice — contiguous, mutable, indexed —
while a list is the everyday sequence.

An empty array literal needs a type annotation. `Array` is invariant, so there
is nothing for the compiler to infer the element type from.

Use `Array.fill(length, value)` to create an array of a given size filled with a value:

```dovetail
let zeros = Array.fill(10, 0)        // [|0, 0, 0, ..., 0|]
let greetings = Array.fill(3, "hi")  // [|"hi", "hi", "hi"|]
```

### Accessing Elements

Use the index operator `arr[i]` or the `.get(i)` method:

```dovetail
let first = numbers[0]       // 1
let second = numbers.get(1)  // 2
```

### Setting Elements

Use the index assignment `arr[i] = value` or the `.set(i, value)` method:

```dovetail
numbers[0] = 99
numbers.set(1, 42)
```

### Array Length

```dovetail
let count = numbers.length  // 5
```

### Cloning

`arr.clone()` creates an independent copy of the array:

```dovetail
let a = [|1, 2, 3|]
let b = a.clone()
b[0] = 99
assert a[0] == 1   // original unchanged
```

### Array Type Syntax

The type of an array is written as `Array<ElementType>`:

```dovetail
function sum(numbers: Array<Int32>): Int32 =
    numbers[0] + numbers[1] + numbers[2]
```

### Nested Arrays

Arrays can contain other arrays:

```dovetail
let matrix: Array<Array<Int32>> = [| [| 1, 2 |], [| 3, 4 |] |]
let value = matrix[0][1]  // 2
```

### Equality and Comparison

Primitive-element arrays support `==`, `!=`, `<`, `>`, `<=`, `>=` (lexicographic comparison):

```dovetail
assert [| 1, 2, 3 |] == [| 1, 2, 3 |]
assert [| 1, 2 |] < [| 1, 3 |]
```

### Iterating Over Arrays

```dovetail
for item in numbers do
    debug(item)
```

### Slices: Shared Array Views

`Slice<T>` is available from the prelude without an import. It is a writable view of part of an `Array<T>`. Creating or re-slicing a view does not copy its elements.

Slicing uses `[| ... |]`, matching the array literal delimiters. Element access and assignment still use `[i]`:

```dovetail
let values = [|10, 20, 30, 40, 50|]
let middle: Slice<Int32> = values[|1..4|]
assert middle.length == 3
assert middle[0] == 20

middle[0] = 99
assert values[1] == 99   // writes through to the original array
values[2] = 77
assert middle[1] == 77   // observes writes through the array too

let tail = middle[|1..|]
assert tail[0] == 77     // bounds are relative to middle
```

All slicing forms work on both arrays and slices:

| Form | Elements included |
|---|---|
| `values[\|i..j\|]` | From `i` up to, but excluding, `j` |
| `values[\|i..\|]` | From `i` through the end |
| `values[\|..j\|]` | From zero up to, but excluding, `j` |
| `values[\|..\|]` | The whole array or slice |
| `values[\|i..=j\|]` | From `i` through `j`, including `j` |
| `values[\|..=j\|]` | From zero through `j`, including `j` |

`values[|i|]` and `values[i..j]` are invalid. Use `values[i]` for one element. Range assignment is unsupported; use `copyTo` to copy several elements. The range notation belongs to slicing syntax: `let range = 1..3` is not a valid expression.

### Slice Bounds and Constructors

Bounds are `Int32` values. A half-open interval requires `0 <= start <= end <= length`. An inclusive end must refer to an existing element. Invalid construction, re-slicing, or element access panics; negative indices do not count back from the end. Empty half-open slices are valid, including one at the array's end:

```dovetail
let empty = values[|values.length..|]
assert empty.isEmpty()

let whole = Slice.full(values)
let window = Slice.make(values, 1, 3)  // start and length
assert window == whole.slice(1, 4)    // start and exclusive end
assert window == whole.sliceInclusive(1, 3)
assert window == whole.drop(1).take(3)
```

`make` takes a **length**; `slice` takes an **exclusive end**. The backing array, start, and length are private. Copying a slice value shares the same view of the data. Ordinary locals, parameters, and returns carry the view directly; storing it at an erased or boxed boundary, such as an array element or `Option<Slice<T>>` payload, can allocate a box for the view.

### Copying, Comparing, and Iterating

`toArray()` produces an independent copy. `copyTo(destination)` copies all source elements into a destination slice whose length must be at least the source length. It also works when the views overlap:

```dovetail
let copied = middle.toArray()
copied[0] = 0
assert middle[0] == 99

let shifted = [|1, 2, 3, 4|]
shifted[|..3|].copyTo(shifted[|1..|])
assert shifted == [|1, 1, 2, 3|]
```

Read-only views use the private tuple newtype `ReadonlySlice<T>`:

```dovetail
let array = [|10, 20, 30|]
let view = array[|1..|].readonly
assert view[0] == 20
let subview = view[|..1|]          // also ReadonlySlice<Int32>
let copy = view.toArray()         // independent mutable array
array[1] = 99
assert view[0] == 99              // read-only does not freeze other aliases
assert copy[0] == 20
```

Arrays and slices expose `.readonly` without copying elements. Read-only views support the same checked ranges, iteration, equality, and display as mutable slices. `map` returns fresh backing storage as a read-only view; `copyTo` accepts a mutable destination slice. Indexed writes and `.set` are unavailable. Both slice types use trait-based element access: `Index<Int32>` for reads, and `IndexSet<Int32>` for mutable writes.

Slices compare by contents with `==` and `!=` when their elements implement `Equatable`, even if they view different arrays. They support `Display` when their elements do. Use `for` to iterate over a slice:

```dovetail
let mutable total = 0
for value in middle do
    total = total + value
assert total == 216
```

### Slices and Strings

Strings do not support slicing syntax. Convert explicitly to a character array and then create a view. `chars()` copies the characters once; subsequent slicing shares that array:

```dovetail
let characters = Slice.full("hello".chars())
let greetingStart = characters[|..2|]
assert greetingStart[0] == 'h'
assert greetingStart[1] == 'e'
```

---

## 6.8 Modules

A **module** is a named container that groups **functions**, **properties**, and **top-level `let`** (globals) under one name (similar to F# modules). Modules do not contain type declarations. You use its contents via the qualifier: `ModuleName.member`. There are **two kinds** of modules, depending on whether a type with the same name exists in the package. In a **generic** module (e.g. `module Array<T> =`), **all** members and globals have the type parameter in scope, and globals are **instantiated per type argument** (like C#): each `Array<Int32>`, `Array<String>`, etc. has its own copy of each static and each top-level `let`.

### Standalone modules

When **no type** in the package has the same name as the module, it's a **standalone module**. It can contain only static functions, static properties (`property name(): Type = ...`), and top-level `let` (static). No instance members.

```dovetail
package standard

module Math =
    let Pi: Float64 = 3.141592653589793
    property pi(): Float64 = 3.141592653589793
    function floor(x: Float64): Int32 = ...
    function ceil(x: Float64): Int32 = ...
```

You import the module as a whole and use qualified names:

```dovetail
import standard.Math

let x = Math.floor(3.14)
let p = Math.Pi
```

You cannot import a single member (e.g. `import standard.Math.floor` is not allowed).

### Modules for a type

When a **type with the same name** as the module exists in the package (e.g. type `Array<T>` and module `Array`), the module is a **module for that type**. It may contain instance methods (functions with `self`), instance properties (`property name(self): Type = ...`), static methods and static properties, and top-level `let` (static/global). For a generic type, the module must declare the type parameters: `module Array<T> =`.

In a **generic** module, **all** members and top-level `let` have the type parameter `T` in scope. Static members and globals are **instantiated per type argument** (like C#): `Array<Int32>.defaultCapacity` and `Array<String>.defaultCapacity` are different storage locations.

```dovetail
package standard.prelude

// Type Array<T> is declared elsewhere (e.g. intrinsic).
module Array<T> =
    let defaultCapacity: Int32 = 16
    property empty(): Array<T> = ...
    function fill(size: Int32, value: T): Array<T> = ...
    function get(self, index: Int32): T = ...
    function set(self, index: Int32, value: T): Unit = ...
    property length(self): Int32 = ...
```

**Instance members are always available on the type.** You do not need to import the module to call `arr.length` or `arr.get(0)` — whenever the type is in scope, the instance methods and properties from that type's module are available.

**Static methods** can infer the module's type arguments from call arguments or an expected return type: `Array.fill(5, 42)` infers `Int32`, and `let empty: Array<Int32> = Array.empty()` uses the annotation. You can also supply them explicitly, as in `Array<Int32>.fill(5, 42)`. For a generic global, qualify its instantiation explicitly, such as `Array<Int32>.defaultCapacity`. Static use requires the module to be in scope (same package, prelude, or imported).

A package may have **at most one** module for a given module name (standalone or for a type).

---

## 6.9 Extension Methods

**Extension methods** let you add methods to types you don't own — especially types from another package. Every extension has a name (e.g. `UserHelpers`) and defines methods (and static methods) on a type. Extensions must be **imported** to be used; they are not attached automatically.

```dovetail
package myapp

import users.User  // User is defined in another package

extension UserHelpers for User =
    function displayName(self): String =
        "${self.firstName} ${self.lastName}"
```

Why give extensions a name and require import?

1. **Explicit imports** — You must import the extension to use its methods, so it's clear where they come from.
2. **Avoid conflicts** — Different packages can define extensions with different names for the same type.
3. **Clear ownership** — The extension name shows which package or layer provides the behavior.

Using extensions:

```dovetail
package app

import users.User
import myapp.UserHelpers  // Must import the extension

function main() =
    let user = User { firstName = "Alice"; lastName = "Smith" }
    debug(user.displayName())  // Works because UserHelpers is imported
```

For **types in the same package**, instance methods are usually provided by a **module for that type** (a module with the same name as the type), not by an extension. See [Modules](https://dovetaillang.org/book/type-system.md#68-modules) above. Use an **extension** when you want to add methods to a type from another package or when you want a separate, explicitly imported set of methods.

---

## 6.10 The Any Type and Type Casting

### The Any Type

`Any` is the **top type** in Dovetail — every type is assignable to `Any`:

```dovetail
let a: Any = "Hello"
let b: Any = 42
let c: Any = true
let d: Any = Point { x = 1; y = 2 }
```

This makes `Any` useful for heterogeneous collections, generic APIs that accept values of unknown type, and interop scenarios. Under the hood, primitive values (integers, floats, booleans, etc.) are automatically **boxed** when stored as `Any`, and **unboxed** when cast back to their concrete type.

### Type Testing with `is`

The `is` expression checks at runtime whether a value has a specific type. It returns `Bool`:

```dovetail
function describe(x: Any): String =
    if x is String then "a string"
    else if x is Int32 then "an integer"
    else if x is Bool then "a boolean"
    else "something else"
```

`is` supports concrete target types, including primitives, records, enums, generic types, and arrays:

```dovetail
let x: Any = Some(42)
x is Option<Int32>    // true
x is Option<String>   // false
x is String           // false
```

### Type Casting with `as`

The `as` expression casts a value to a specific type. If the cast fails at runtime, it **panics** (there is no safe `as?` variant):

```dovetail
let x: Any = 42
let n: Int32 = x as Int32   // succeeds, n is 42

let y: Any = "hello"
let s: String = y as String  // succeeds, s is "hello"
```

For primitive types, `as` automatically unboxes the value:

```dovetail
let x: Any = 3.14
let f: Float64 = x as Float64   // unboxes to 3.14
```

For records and enums, `as` returns the reference directly:

```dovetail
record Point =
    x: Int32
    y: Int32

let x: Any = Point { x = 1; y = 2 }
let p: Point = x as Point
assert p.x == 1
```

### The `is` + `as` Pattern

Since `as` panics on failure, the idiomatic pattern is to test first with `is`, then cast:

```dovetail
function tryGetInt(x: Any): Option<Int32> =
    if x is Int32 then Some(x as Int32)
    else None
```

Or in a more complex example:

```dovetail
function processValue(x: Any): String =
    if x is Int32 then
        let n = x as Int32
        "integer: ${n * 2}"
    else if x is String then
        let s = x as String
        "string of length ${s.length}"
    else
        "unknown"
```

### Restrictions

For the concrete type recovery shown here, the subject is `Any`. These operators
also support [class type tests and casts](https://dovetaillang.org/book/classes.md) and
[interface upcasts](https://dovetaillang.org/book/type-system.md#611-interfaces-and-interface-types), subject to their own rules.
They do not convert unrelated concrete types:

```dovetail
let x: Int32 = 42
// x is String    // compile error: 'is' requires subject of type Any
// x as String    // compile error: 'as' requires subject of type Any
```

For recovery from `Any`, the target must be concrete; `Any`, `Never`, and
interface targets are unsupported:

```dovetail
let x: Any = 42
// x is Any       // compile error: target must be a concrete type
// x is Never     // compile error: target must be a concrete type
```

### Working with Generic Types

`is` and `as` work with generic type instantiations:

```dovetail
let x: Any = Some(42)
if x is Option<Int32> then
    let opt = x as Option<Int32>
    match opt with
        case Some(n) => assert n == 42
        case None => panic "unexpected"
```

Different instantiations are distinguished at runtime:

```dovetail
let a: Any = Some(42)
let b: Any = Some("hello")

a is Option<Int32>     // true
a is Option<String>    // false
b is Option<String>    // true
```

### Working with Arrays

Array element types are also distinguished:

```dovetail
let x: Any = [|1, 2, 3|]
x is Array<Int32>      // true
x is Array<String>     // false
```

---

## 6.11 Interfaces and Interface Types

An `interface` describes behavior and can also be the type of a value. It lets a
parameter, return value, field, or collection hold different implementations of
the same contract. A plain `trait` describes behavior for generic bounds; it
cannot appear as a value type. Both use `implement` blocks, and an interface can
also be used as a generic bound.

### Declaring and Implementing Interfaces

```dovetail
interface Label =
    function text(self): String

record Person =
    name: String

record NumberLabel =
    value: Int32

implement Label for Person =
    function text(self): String = self.name

implement Label for NumberLabel =
    function text(self): String = "${self.value}"

record Badge =
    label: Label

function readLabel(label: Label): String = label.text()

function chooseLabel(person: Bool): Label =
    if person then Person { name = "Ada" }
    else NumberLabel { value = 42 }

function main(): Unit =
    let label: Label = Person { name = "Ada" }
    assert label.text() == "Ada"
    assert readLabel(NumberLabel { value = 42 }) == "42"
    assert chooseLabel(false).text() == "42"
    let badge = Badge { label = Person { name = "Grace" } }
    assert badge.label.text() == "Grace"
    let labels: List<Label> = [Person { name = "Ada" }, NumberLabel { value = 42 }]
    for item in labels do
        assert item.text().length > 0
```

The compiler implicitly converts each concrete value to `Label` where that type
is expected. Calling `text` through `Label` dispatches to the implementation of
the value held at runtime. Records, enums, primitives, and classes can implement
interfaces. Only the interface's members are exposed through an interface value.

Type annotations make the intended common interface explicit. They also allow a
list literal to contain different concrete implementations. An existing
`List<Person>` does not automatically become `List<Label>`: convert the elements
when building the new collection. The same boundary applies to containers such
as `Option<T>` and to function types; coercion does not recursively adapt them.

### Generic Interfaces and Bounds

An interface can have type parameters:

```dovetail
interface Source<T> =
    function get(self): T

record Fixed =
    value: Int32

implement Source<Int32> for Fixed =
    function get(self): Int32 = self.value

function read<T>(source: T): Int32 where T: Source<Int32> = source.get()

function main(): Unit =
    let source: Source<Int32> = Fixed { value = 7 }
    assert source.get() == 7
    assert read(Fixed { value = 9 }) == 9
    assert read(source) == 7
```

`Source<Int32>` fixes the element type while hiding the implementation. A generic
bound retains the caller's type: passing `Fixed` allows static dispatch, while
passing an interface value still calls through that value's interface. Individual
interface methods cannot introduce their own type parameters.

### Intersections and Upcasts

`A and B` is a value type requiring both interfaces. Its components must all be
interfaces, and the concrete value must implement every component:

```dovetail
interface Named =
    function name(self): String

interface Counted =
    function count(self): Int32

record Team =
    title: String
    members: Int32

implement Named for Team =
    function name(self): String = self.title

implement Counted for Team =
    function count(self): Int32 = self.members

function main(): Unit =
    let team: Named and Counted = Team { title = "Core"; members = 3 }
    assert team.name() == "Core"
    assert team.count() == 3
    let named: Named = team
    let counted = team as Counted
    assert named.name() == "Core"
    assert counted.count() == 3
```

An intersection implicitly upcasts to a component or a smaller intersection;
`as` can also express an upcast. An interface extending another interface can
likewise upcast to its parent. These conversions expose fewer capabilities and
do not discover new ones at runtime. If components declare the same member,
qualify the call, such as `Named.name(team)`, to select the contract explicitly.

### Inheritance, Defaults, and `Self`

Interfaces share inheritance, default methods and properties, and explicit
member qualification with traits. See [Part 8, sections 8.5–8.7](https://dovetaillang.org/book/traits.md#85-trait-and-interface-inheritance)
for the implementation rules. An interface can extend only other interfaces;
a trait can extend traits or interfaces.

An interface method may return bare `Self`:

```dovetail
interface Stepper =
    function step(self): Self
    function value(self): Int32

record Counter =
    n: Int32

implement Stepper for Counter =
    function step(self): Counter = Counter { n = self.n + 1 }
    function value(self): Int32 = self.n

function main(): Unit =
    let counter: Stepper = Counter { n = 4 }
    let next: Stepper = counter.step()
    assert next.value() == 5
```

Through an interface value, the result has the interface type that declares the
method. For an intersection receiver, it has that declaring component's type,
so calling a `Self`-returning method does not preserve the whole intersection.

### Interface Restrictions and `Any`

The compiler checks these rules when the interface is declared:

- Every method takes `self`; static methods are not allowed.
- Methods cannot declare their own generic parameters.
- Associated types, including generic associated types, are not allowed.
- `Self` is allowed as the receiver and as a bare return type. Parameters such as
  `other: Self` and nested returns such as `Option<Self>` are not allowed.
- Parent contracts in `extends` must themselves be interfaces.

Use a trait when a contract needs these excluded features. For example,
`equals(self, other: Self)` belongs in a trait because both arguments must have
the same concrete type.

Interface values and [`Any`](https://dovetaillang.org/book/type-system.md#610-the-any-type-and-type-casting) serve different
purposes. An interface exposes a known contract. `Any` requires a concrete type
test or cast before using the value. Testing `value is Label` or casting an
`Any` value to `Label` is unsupported. Storing an interface value in `Any` retains
the interface wrapper: testing that `Any` for the underlying record type returns
false. Store the concrete record directly in `Any` when concrete type recovery
is needed.

### Choosing a Contract

| Need | Use |
|------|-----|
| Heterogeneous collection, runtime-selected return, or injected dependency field | Interface |
| One contract usable both as a generic bound and a value type | Interface, within the declaration restrictions |
| Same-type arguments, static methods, associated types, or generic methods | Trait |
| Generic behavior where static dispatch is sufficient | Trait |
| A closed, known set of alternatives with pattern matching | Enum |
| Shared state and a single class inheritance hierarchy | Abstract class |

---

## Private Construction for Records and Enums

A public type can expose its shape while reserving construction for its associated
module:

```dovetail
public record Account private =
    balance: Int32

module Account =
    public function make(balance: Int32): Account =
        assert balance >= 0
        Account { balance = balance }

    public function deposit(self, amount: Int32): Account =
        assert amount >= 0
        self with { balance = self.balance + amount }

public enum Status private =
    Open
    Closed

module Status =
    public function open(): Status = Status.Open
    public function close(self): Status = Status.Closed
```

Outside `module Account`, reading `account.balance` and matching record fields
are allowed; record construction and `with` expressions are rejected. Outside
`module Status`, variants can appear in patterns but cannot construct values.
The module must belong to the type's defining package. Trait implementations and
extensions must call module functions for construction and updates.

Place the modifier after type parameters and before constraints, for example
`record Box<T> private where T: Equatable = ...`. Empty private records use
`record Token private`. Leading `public` controls visibility of the type itself.

Private newtypes also use this placement, but retain stronger inspection rules:
only their module can access `.value` or unwrap a constructor pattern. Trait
implementations must use module functions for those operations too. Derive macros
receive no exemption from these restrictions. The old `newtype Name = private Type`
syntax is rejected.

Choose privacy per type. If `OrderStatus` is private, `module Order` cannot directly
construct `OrderStatus.Placed(...)`; it must use `module OrderStatus` functions.
An aggregate can instead keep `Order` construction private while leaving its
status enum publicly constructible.

---

## Summary

- **Type Inference**: Dovetail infers types when possible, but you can be explicit
- **Records**: Data-only types with named fields, immutable by default
- **Enums**: Discriminated unions that can carry data per variant
- **Tuples**: Positional grouping of values (anonymous types; access via _0, _1, or destructuring)
- **Newtypes**: Distinct types for type safety
- **Type Aliases**: Convenient names for existing types
- **Lists**: Immutable linked sequences, with `[ ... ]` literals, `::` prepending, and `++` concatenation
- **Arrays**: Fixed-size indexed collections, with `[| ... |]` literals
- **Slices**: Writable shared array views, with `[|start..end|]` slicing and `[i]` element access
- **Modules**: Named containers (standalone or for a type); qualified use; instance members of a module-for-type are available on the type. In generic modules, all members and globals have T in scope and are instantiated per type argument (C#-style); static methods can infer type arguments; generic globals use an explicit instantiation such as `Array<Int32>.defaultCapacity`
- **Extension methods**: Add methods to types (e.g. from other packages); always named and must be imported to use
- **Any type**: Top type; every value is assignable to `Any`; use `is` to test and `as` to cast back to concrete types

- **Interfaces**: Contracts usable as value types and generic bounds; implicit coercion enables runtime dispatch, heterogeneous collections, and interface intersections


---

# Part 7: Generics

Source: https://dovetaillang.org/book/generics/


Generics allow you to write code that works with multiple types while maintaining type safety. Instead of writing separate functions for each type, you write one generic version.

---

## 7.1 Generic Functions

### Basic Generic Functions

Use angle brackets to declare type parameters:

```dovetail
function identity<T>(x: T): T = x

// Use with different types
let a = identity(42)        // T is Int32
let b = identity("hello")   // T is String
let c = identity(true)      // T is Bool
```

The compiler infers the type argument from the value you pass.

### Multiple Type Parameters

Functions can have multiple type parameters:

```dovetail
function first<A, B>(a: A, b: B): A = a
function second<A, B>(a: A, b: B): B = b

let x = first(10, "hello")   // A is Int32, B is String, returns 10
let y = second(10, "hello")  // returns "hello"
```

### Explicit Type Arguments

Sometimes you need to specify type arguments explicitly:

```dovetail
function create<T>(): Array<T> = [||]

// Must specify T since it can't be inferred
let numbers = create<Int32>()
let names = create<String>()
```

### Type Parameter Scope

Type parameters are in scope for the entire function:

```dovetail
function swap<T>(pair: (T, T)): (T, T) =
    let (a, b) = pair
    (b, a)

let swapped = swap((1, 2))  // (2, 1)
```

---

## 7.2 Generic Types

### Generic Records

Records can have type parameters:

```dovetail
record Box<T> =
    value: T

let intBox = Box { value = 42 }
let stringBox = Box { value = "hello" }
```

### Generic Records with Multiple Parameters

```dovetail
record Pair<A, B> =
    first: A
    second: B

let pair = Pair { first = 1; second = "one" }
let x = pair.first   // Int32
let y = pair.second  // String
```

### Generic Enums

Enums can also be generic:

```dovetail
enum Option<T> =
    Some(T)
    None

function divide(a: Int32, b: Int32): Option<Int32> =
    if b == 0 then
        None
    else
        Some(a / b)

let result = divide(10, 2)
match result with
    case Some(value) => debug("Result: $value")
    case None => debug("Cannot divide by zero")
```

### Result Type

The `Result` type uses two type parameters:

```dovetail
enum Result<T, E> =
    Ok(T)
    Error(E)

function divideOrError(a: Int32, b: Int32): Result<Int32, String> =
    if b == 0 then
        Error("Cannot divide by zero")
    else
        Ok(a / b)

let result = divideOrError(10, 2)  // Ok(5)
```

### Generic Classes

Classes can have type parameters:

```dovetail
class Container<T>(value: T) =
    function get(self): T = self.value
    
    function set(self, newValue: T): Container<T> =
        Container(newValue)

let container = Container(42)
let value = container.get()  // 42
```

---

## 7.3 Constraints

A constraint says what a type must support before it can be used with your generic code. For example, a function that compares two values needs a type that supports comparison.

### Basic Constraints

Use the `where` clause to add constraints:

```dovetail
trait Printable =
    function format(self): String

function printIt<T>(x: T): String
    where T: Printable
= x.format()
```

Now `printIt` can only be called with types that implement `Printable`:

```dovetail
implement Printable for Int32 =
    function format(self): String = "$self"

printIt(42)      // OK - Int32 implements Printable
// printIt([1, 2])  // Error - List doesn't implement Printable
```

### Multiple Constraints

You can require multiple traits using `+`:

```dovetail
trait Showable =
    function show(self): String

trait Countable =
    function count(self): Int32

function describe<T>(x: T): String
    where T: Showable + Countable
= "${x.show()} (count: ${x.count()})"
```

Or list them separately:

```dovetail
function describe<T>(x: T): String
    where T: Showable, T: Countable
= "${x.show()} (count: ${x.count()})"
```

### Inline Constraints

For simple cases, you can put the constraint inline:

```dovetail
function printIt<T: Printable>(x: T): String = x.format()
```

This is equivalent to using a `where` clause.

### Constraints on Multiple Type Parameters

```dovetail
function combine<A, B>(a: A, b: B): String
    where A: Showable, B: Showable
= "${a.show()} and ${b.show()}"
```

### Constraints on Generic Types

Records, enums, and classes can also have constraints:

```dovetail
record SortedPair<T>
    where T: Comparable
=
    first: T
    second: T

// Only types that implement Comparable can be used
let pair = SortedPair { first = 1; second = 2 }  // OK
```

### Common Trait Constraints

Some commonly used trait constraints:

- `Equatable` - allows `==` and `!=` comparisons
- `Comparable` - allows `<`, `>`, `<=`, `>=` comparisons
- `Printable` - can be formatted as a string

```dovetail
function findMax<T>(a: T, b: T): T
    where T: Comparable =
    if a > b then a else b

let bigger = findMax(10, 20)  // 20
```

---

## Summary

- Use `<T>` to write a function or type that works with different types.
- The compiler usually infers type arguments from the values you pass.
- Use explicit type arguments, such as `<Int32>`, when needed.
- Use `where T: Trait` to require operations your generic code needs.

For generic extensions, class constraints, method-specific bounds, variance,
and runtime type matching, continue with [Part 26: Advanced Generics](https://dovetaillang.org/book/advanced-generics.md).


---

# Part 8: Traits and Implementations

Source: https://dovetaillang.org/book/traits/


Traits define shared behavior that types can implement and generic functions can
require through bounds. When a contract must also be a value type, use an
[interface](https://dovetaillang.org/book/type-system.md#611-interfaces-and-interface-types). Traits and
interfaces share implementation blocks, inheritance, defaults, and explicit
member qualification.

---

## 8.1 Defining Traits

### Basic Trait Definition

A trait declares a set of methods that types must implement:

```dovetail
trait Printable =
    function format(self): String
```

Traits can have multiple methods:

```dovetail
trait Describable =
    function describe(self): String
    function summary(self): String
```

### Traits with Parameters

Trait methods can take parameters:

```dovetail
trait Comparable =
    function compare(self, other: Self): Ordering
```

The `Self` type refers to the implementing type.

### Generic Traits

Traits can have type parameters:

```dovetail
trait Container<T> =
    function get(self): T
    function set(self, value: T): Self
```

---

## 8.2 Implementing Traits

### Basic Implementation

Use `implement` to make a type conform to a trait:

```dovetail
record Point =
    x: Int32
    y: Int32

trait Printable =
    function format(self): String

implement Printable for Point =
    function format(self): String =
        "(${self.x}, ${self.y})"

let p = Point { x = 3; y = 4 }
p.format()  // "(3, 4)"
```

### Implementing Multiple Traits

A type can implement multiple traits:

```dovetail
trait Printable =
    function format(self): String

trait Describable =
    function describe(self): String

record User =
    name: String
    age: Int32

implement Printable for User =
    function format(self): String = self.name

implement Describable for User =
    function describe(self): String =
        "${self.name} is ${self.age} years old"
```

### Implementing Traits for Enums

```dovetail
enum Color =
    Red
    Green
    Blue

trait Printable =
    function format(self): String

implement Printable for Color =
    function format(self): String =
        match self with
            case Red => "red"
            case Green => "green"
            case Blue => "blue"
```

### Implementations and Private Types

An `implement` block does not gain access to a type's private operations. For private records and enums, it may read fields and match patterns, but must call associated-module functions to construct values or update a record with `with`. A private newtype also requires module functions to inspect its wrapped value:

```dovetail
newtype Amount private = Int32

module Amount =
    public function make(value: Int32): Amount =
        assert value >= 0
        Amount(value)

    public function read(self): Int32 = self.value

trait Counted =
    function count(self): Int32

implement Counted for Amount =
    public function count(self): Int32 = self.read()
```

Writing `self.value` or an `Amount(value)` pattern directly in that implementation is an error. The rule also applies to generic implementations, extensions, and generated implementations; sharing the defining package does not grant access.

### Implementing Generic Traits

```dovetail
trait Container<T> =
    function get(self): T

record Box<T> =
    value: T

implement <T> Container<T> for Box<T> =
    function get(self): T = self.value
```

### Trait Properties

Traits can declare properties that types must provide. Properties in traits define getters that implementations must satisfy:

```dovetail
trait Measurable =
    property size(self): Int32

record Box =
    width: Int32
    height: Int32
    depth: Int32

implement Measurable for Box =
    property size(self): Int32 = self.width * self.height * self.depth

function main(): Unit =
    let b = Box { width = 2; height = 3; depth = 4 }
    assert b.size == 24  // calls the property getter
```

Key points about trait properties:
- Declared with `property name(self): Type`; an optional body provides a default
- Implementations without a default provide the property using `property name(self): Type = expression`
- Properties are accessed like fields but call getter functions
- Properties are evaluated every time they're accessed

### Implementing Trait Properties

When implementing a trait with properties, provide the property implementation(self):

```dovetail
trait Stats =
    property average(self): Int32
    property total(self): Int32

record DataSet =
    values: (Int32, Int32, Int32)

implement Stats for DataSet =
    property total(self): Int32 =
        self.values._0 + self.values._1 + self.values._2

    property average(self): Int32 =
        self.total / 3

function main(): Unit =
    let data = DataSet { values = (10, 20, 30) }
    assert data.total == 60
    assert data.average == 20
```

Trait properties can reference each other in implementations, just like class body properties can reference other fields.

### Combining Trait Methods and Properties

Traits can have both methods and properties:

```dovetail
trait Shape =
    property area(self): Int32
    property perimeter(self): Int32
    function describe(self): String

record Rectangle =
    width: Int32
    height: Int32

implement Shape for Rectangle =
    property area(self): Int32 = self.width * self.height
    property perimeter(self): Int32 = 2 * (self.width + self.height)

    function describe(self): String = "Rectangle(${self.width}x${self.height})"
```

### Using Trait Methods

Once a trait is implemented, you can call its methods:

```dovetail
let user = User { name = "Alice"; age = 30 }
debug(user.format())     // "Alice"
debug(user.describe())   // "Alice is 30 years old"
```

### Trait Bounds in Functions

Use traits as constraints in generic functions:

```dovetail
function printAll<T>(items: Array<T>): Unit
    where T: Printable =
    for item in items do
        debug(item.format())
```

### Automatic Import of Implementations

Trait implementations are automatically imported along with types and traits. You never need to explicitly import implementations.

**Importing a type brings its implementations:**

When you import a type, all trait implementations for that type (defined in its package) come with it.

```dovetail
// In package "users"
record User =
    name: String
    email: String

implement Equatable for User = ...
implement Comparable for User = ...
implement JsonSerializable for User = ...
```

```dovetail
// In your code
import users.User

// All implementations from the users package come with User
let u1 = User { name = "Alice"; email = "alice@example.com" }
let u2 = User { name = "Bob"; email = "bob@example.com" }
u1 == u2           // Equatable works
u1 < u2            // Comparable works
u1.toJson()        // JsonSerializable works
```

**Importing a trait brings its implementations:**

When you import a trait, all implementations of that trait (defined in its package) come with it.

```dovetail
// In package "serialization"
trait JsonWriter =
    function writeJson(self, value: Any): String

implement JsonWriter for FileOutput = ...
implement JsonWriter for StringBuffer = ...
implement JsonWriter for HttpResponse = ...
```

```dovetail
// In your code
import serialization.JsonWriter

// All implementations from the serialization package come with JsonWriter
// You can now use JsonWriter methods on FileOutput, StringBuffer, HttpResponse
```

---

## 8.3 Core Traits

Dovetail provides several built-in traits that enable common operations.

### Equatable

Enables `==` and `!=` comparisons:

```dovetail
trait Equatable =
    function equals(self, other: Self): Bool
```

Primitive types have prelude implementations of `Equatable`. Records and enums can request structural equality with `@derive(Equatable)` when their fields/variants are equatable.

```dovetail
@derive(Equatable)
record Point =
    x: Int32
    y: Int32

// Derived equality compares the Int32 fields
let p1 = Point { x = 1; y = 2 }
let p2 = Point { x = 1; y = 2 }
p1 == p2  // true
```

### Identity Equality and Hashing

`ClassIdentity` uses **reference identity**, not the contents of an object. Two separately created instances of the same class have different identities, even when all their fields contain equal values. Two references to the same instance share its identity.

Classes can implement equality and hashing explicitly using reference identity:

```dovetail
class IdentityBox<T>(public value: T)

implement <T> Equatable for IdentityBox<T> =
    public function equals(self, other: IdentityBox<T>): Bool =
        ClassIdentity.equals(self, other)

implement <T> Hashable for IdentityBox<T> =
    public function hash(self): Int64 = ClassIdentity.hash(self)

function checkBoxIdentity(): Unit =
    let first = IdentityBox(42)
    let second = IdentityBox(42)
    let alias = first
    assert !ClassIdentity.equals(first, second)  // Same contents, different instances
    assert ClassIdentity.equals(first, alias)    // Two references to one instance
    assert first != second                     // The Equatable implementation above uses identity
```

The element type needs no equality or hashing bounds: these implementations use the box's identity. Neither implementation is automatic, and an implementation for a base class does not automatically provide one for every subclass.

`Hashable.hash` returns an `Int64`. Whenever two values compare equal through `Equatable`, their trait hashes must match. Collisions between unequal values are permitted. A class using structural equality should therefore hash its equality-relevant contents; using identity hashing for structurally equal but distinct objects would generally violate the contract.

Raw `ClassIdentity.equals` and `ClassIdentity.hash` remain available even if a class defines structural trait implementations. They do not call those implementations. The current mutable hash collections also require `Default` for keys; providing these two traits alone does not remove that separate requirement. A class can implement `Default` using a shared placeholder instance when that is safe for its API. For example, the runtime's `Waiter` uses one global instance with an empty suspended-fiber stack for unused hash-table slots, while real scheduler conditions always allocate fresh instances. The collections track occupied slots separately and do not mutate this placeholder's suspended-fiber stack.

### Indexed reads and writes

`Index<K>` enables `value[key]` on user types. Its associated `Output` is the read result. `IndexSet<K>` independently enables `value[key] = item`; its associated `Value` is the accepted item type. Keys need not be integers.

```dovetail
function read<C, K, T>(collection: C, key: K): T where C: Index<K, Output = T> = collection[key]

function write<C, K, T>(collection: C, key: K, item: T): Unit where C: IndexSet<K, Value = T> = collection[key] = item
```

`Slice<T>` implements both capabilities with `Int32` keys. `ReadonlySlice<T>` implements only reads. A method named `get` or `set` does not grant the corresponding syntax without the trait. Array and String indexing retain their built-in behavior; they do not implement these traits. Range slicing (`[|start..end|]`) is a separate operation.

Implementations are selected by receiver and compatible key parameter type, using ordinary argument assignability. Neither the expected read result nor the assigned value resolves ambiguous implementations. Receiver, key, and value are evaluated once, in that order.


### Arithmetic operators and associated output constraints

`Add<R>`, `Sub<R>`, `Mul<R>`, and `Div<R>` overload `+`, `-`, `*`, and `/`.
Each declares an associated `Output` and a method named `add`, `sub`, `mul`, or `div`:

```dovetail
public trait Add<R> =
    type Output
    function add(self: Self, rhs: R): Output
```

The operands select the implementation, whose `Output` determines the result.
Numbers implement these traits with native arithmetic; `Uint128` supports addition,
subtraction, and multiplication, but not division. Strings concatenate with `++`.

Generic functions constrain associated outputs using equality bindings in bounds:

```dovetail
function add<L, R, O>(left: L, right: R): O where L: Add<R, Output = O> =
    left + right
```

The compiler can infer `O` from the matching implementation. A function returning
its left operand's type instead uses `where L: Add<R, Output = L>`; `Output = Self`
is never assumed. The same bindings work for ordinary trait methods and for
associated types nested inside other types. Positional trait arguments precede
bindings. A helper can also name an implementation's output as `T.Output`.
See [Associated Outputs](https://dovetaillang.org/book/advanced-generics.md#268-associated-outputs) for a
complete example. Equality bindings for generic associated types remain unsupported.

Newtypes must implement each capability explicitly, including `Equatable` and
`Comparable`. Wrapping a number or String does not grant its operators. Public
newtypes may opt into structural equality with `@derive(Equatable)`. Private
newtypes delegate through their associated modules to preserve access rules.

### Unary negation

`Neg` lets library types overload unary `-` without changing their result type:

```dovetail
public trait Neg =
    function negate(self: Self): Self

function opposite<T>(value: T): T where T: Neg = -value
```

`BigInt` and `Decimal` implement `Neg`. Primitive signed integers and floats
retain their native unary negation; this trait does not add implicit conversions.

### Concat

Overloads `++`, the concatenation operator:

```dovetail
trait Concat<R> =
    type Output
    function concat(self: Self, rhs: R): Output
```

`++` is deliberately separate from `+`: `+` is arithmetic, while `++` is "join these two things". Implementing `Concat` does not overload `+`, and vice versa.

`String` implements `Concat<String>` with `Output = String`, backed by native concatenation. Other types opt in:

```dovetail
record Line =
    text: String

implement Concat<Line> for Line =
    type Output = Line
    function concat(self: Line, other: Line): Line =
        Line { text = self.text ++ other.text }

let joined = Line { text = "a" } ++ Line { text = "b" }
```

Like `Div`, the right-hand type is a parameter and `Output` is an associated type, so the operands need not match and the result need not be `Self`:

```dovetail
implement Concat<String> for Line =
    type Output = Line
    function concat(self: Line, other: String): Line = Line { text = self.text ++ other }
```

`++` is left-associative and binds at the same level as `+`.

### Comparable

Enables ordering comparisons (`<`, `>`, `<=`, `>=`):

```dovetail
trait Comparable =
    function compare(self, other: Self): Ordering  // Less, Equal, or Greater
```

Numeric types and strings implement `Comparable` by default.

```dovetail
function max<T>(a: T, b: T): T
    where T: Comparable =
    if a > b then a else b

max(10, 20)  // 20
```

---

## 8.4 The Orphan Rule

The orphan rule prevents conflicts when multiple packages could implement the same trait for the same type.

### The Rule

You can only implement a trait for a type if:
1. **You own the trait** (it's defined in your package), OR
2. **You own the type** (it's defined in your package)

### Why This Matters

Without this rule, two different packages could implement the same trait for the same type differently, causing conflicts:

```dovetail
// Package A
implement Printable for Int32 =
    function format(self): String = "number: $self"

// Package B (different implementation!)
implement Printable for Int32 =
    function format(self): String = "int($self)"

// Which one should be used? Conflict!
```

### Valid Implementations

```dovetail
// In your package: you own the trait
trait MyTrait =
    function doSomething(self): Int32

// OK - you own the trait
implement MyTrait for Int32 =
    function doSomething(self): Int32 = self * 2
```

```dovetail
// In your package: you own the type
record MyRecord =
    value: Int32

// OK - you own the type
implement Printable for MyRecord =
    function format(self): String = "${self.value}"
```

### Invalid Implementation

```dovetail
// Trying to implement someone else's trait for someone else's type
// ERROR: Orphan rule violation
implement SomeoneElsesTrait for SomeoneElsesType =
    function method(self): Int32 = 0
```

### Working Around the Orphan Rule

If you need to implement a foreign trait for a foreign type, wrap it in a newtype:

```dovetail
// Can't implement ThirdPartyTrait for ThirdPartyType directly
// Solution: wrap it
newtype MyWrapper = ThirdPartyType

implement ThirdPartyTrait for MyWrapper =
    function method(self): Int32 = 42
```

---

## 8.5 Trait and Interface Inheritance

`extends` includes a parent's members in a contract. A trait can extend traits
or interfaces; an interface can extend only interfaces.

```dovetail
interface Named =
    function name(self): String

interface Described extends Named =
    function description(self): String

record Item =
    title: String

implement Described for Item =
    function name(self): String = self.title
    function description(self): String = "Item: ${self.name()}"

function main(): Unit =
    let item: Described = Item { title = "Book" }
    let named: Named = item
    assert named.name() == "Book"
    assert item.description() == "Item: Book"
```

The child implementation supplies inherited requirements in the same block,
unless a default body supplies them. A separate implementation of the parent
does not fill missing members in the child implementation.

Implementing the child also makes the concrete type satisfy the parent. If the
type has a direct parent implementation, that implementation wins when the
parent contract is requested. Otherwise, one child implementation can supply the
parent; multiple possible providers are ambiguous. Inherited methods can share a
name when their parameter lists differ. See
[Inherited Overloads](https://dovetaillang.org/book/advanced-generics.md#2610-inherited-overloads) for an example.

## 8.6 Default Methods and Properties

A trait or interface member can provide a body. An implementation may omit that
member or replace its body. Defaults can call other members of the contract:

```dovetail
trait Measured =
    property size(self): Int32
    property doubled(self): Int32 = self.size * 2
    function describe(self): String = "Size: ${self.size}"

record Batch =
    count: Int32

implement Measured for Batch =
    property size(self): Int32 = self.count

function main(): Unit =
    let batch = Batch { count = 3 }
    assert batch.doubled == 6
    assert batch.describe() == "Size: 3"
```

A child contract can override an inherited default by providing a new body.
Repeating only the inherited signature is not an override. Conflicting defaults
from parents require an explicit implementation to resolve the conflict.

Defaults work in implementation blocks and classes, including generic ones.
Methods with their own type parameters can also provide defaults; see
[Generic Trait Defaults](https://dovetaillang.org/book/advanced-generics.md#267-generic-trait-defaults).
Classes must implement required static trait members explicitly.

## 8.7 Method Resolution and Explicit Disambiguation

For a concrete receiver, applicable members are considered in this order:

1. Members of the receiver type's associated module.
2. Members of imported named extensions.
3. Trait or interface implementations.

Named extensions must be imported even within the same package. Multiple
applicable candidates at the same priority are ambiguous. Qualify a member to
choose its contract or extension explicitly:

```dovetail
trait ShortLabel =
    function label(self): String

trait LongLabel =
    function label(self): String

record Entry =
    title: String

implement ShortLabel for Entry =
    function label(self): String = self.title

implement LongLabel for Entry =
    function label(self): String = "Entry: ${self.title}"

function main(): Unit =
    let entry = Entry { title = "Book" }
    assert ShortLabel.label(entry) == "Book"
    assert LongLabel.label(entry) == "Entry: Book"
```

Use `Trait<Arguments>.method(receiver, arguments)` for a generic contract, or
`ExtensionName.method(receiver, arguments)` for a named extension. Properties
also support qualification as a call with the receiver argument.

Implementations must not overlap: two implementations that could apply to the
same type and contract are rejected. Different `where` bounds do not establish
that implementations are disjoint. A blanket implementation whose target is a
bare type parameter, such as `implement <T> Printable for T`, is unsupported.

---

## Summary

- **Traits** define shared behavior as a set of methods and properties
- **Trait Properties**: Declared with `property name(self): Type`, implementations provide the getter
- **Implementations** make types conform to traits using `implement Trait for Type`
- **Implementing Properties**: Use `property name(self): Type = expression` to satisfy trait property requirements
- **Automatic Imports**: Importing a type brings its trait implementations; importing a trait brings all its implementations
- **Core Traits**: `Equatable` for `==`, `Comparable` for ordering
- **Orphan Rule**: You must own either the trait or the type to implement a trait
- **Workaround**: Use newtypes to wrap foreign types when needed

- **Inheritance**: `extends` includes parent requirements; child implementations supply inherited members or use defaults
- **Defaults**: Methods and properties can supply reusable bodies
- **Disambiguation**: `TraitName.method(receiver)` selects a contract explicitly


---

# Part 9: Classes and Object-Oriented Programming

Source: https://dovetaillang.org/book/classes/


Classes in Dovetail provide object-oriented programming with encapsulation, inheritance, and polymorphism. Unlike records (which are pure data), classes combine data with behavior and support mutable state.

---

## 9.1 Class Definitions

A class is defined with the `class` keyword, followed by the class name, constructor parameters, and methods:

```dovetail
class Point(x: Int32, y: Int32) =
    public function getX(self): Int32 = self.x
    public function getY(self): Int32 = self.y
    public function sum(self): Int32 = self.x + self.y
```

Key points:
- Constructor parameters define the class fields
- Methods are defined in the class body

### Creating Instances

Create instances by calling the class name like a function:

```dovetail
let p = Point(3, 4)
let x = p.getX()     // 3
let total = p.sum()  // 7
```

### Field Access

Fields can be accessed directly (based on visibility):

```dovetail
class Point(public x: Int32, public y: Int32) =
    public function dummy(self): Int32 = 0

function getX(p: Point): Int32 = p.x  // Direct field access
```

---

## 9.2 Methods

### Instance Methods

Instance methods take `self` as the first parameter:

```dovetail
class Counter(mutable value: Int32) =
    public function getValue(self): Int32 = self.value
    public function increment(self): Unit = self.value = self.value + 1
```

### Static Methods (Smart Constructors)

Methods without `self` are static and called on the class itself. Static methods are commonly used as "smart constructors" to provide alternative ways to create instances:

```dovetail
class Point(x: Int32, y: Int32) =
    public function getX(self): Int32 = self.x
    public function origin(): Point = Point(0, 0)           // Smart constructor
    public function fromSingle(v: Int32): Point = Point(v, v)  // Smart constructor
    public function zero(): Int32 = 0                        // Static utility

function main(): Unit =
    let p1 = Point.origin()       // (0, 0)
    let p2 = Point.fromSingle(5)  // (5, 5)
    let p3 = Point(3, 7)          // Primary constructor
    ()
```

Smart constructors can also perform validation:

```dovetail
class PositiveInt private (value: Int32) =
    public function get(self): Int32 = self.value
    
    public function create(n: Int32): Option<PositiveInt> =
        if n > 0 then Some(PositiveInt(n)) else None

function main(): Unit =
    match PositiveInt.create(42) with
        case Some(p) => p.get()
        case None => 0
    ()
```

---

## 9.3 Class Body Fields

Classes can include field declarations in the body using a unified `let` syntax. These fields can be stored fields, properties (computed getters), static fields, or static properties.

### Stored Fields

Basic stored fields allocate memory in each instance:

```dovetail
class Rectangle(width: Int32, height: Int32) =
    let color: String = "blue"
    let name: String = "rectangle"

    public function getColor(self): String = self.color
    public function getName(self): String = self.name

function main(): Unit =
    let r = Rectangle(3, 4)
    r.getColor()  // "blue"
    r.getName()   // "rectangle"
    ()
```

Key points about stored fields:
- They are evaluated when the instance is created
- They are **private** by default (not accessible outside the class)
- They are **immutable** by default
- They can reference constructor parameters and other fields
- Non-let expressions in the class body run as side effects during construction

### Property Fields

Properties generate getter functions that are evaluated each time they're accessed:

```dovetail
class Rectangle(width: Int32, height: Int32) =
    let property area: Int32 = self.width * self.height
    let property perimeter: Int32 = 2 * (self.width + self.height)

    public function getArea(self): Int32 = self.area      // Calls generated getter
    public function getPerimeter(self): Int32 = self.perimeter

function main(): Unit =
    let r = Rectangle(3, 4)
    r.getArea()      // 12 - computed on access
    r.getPerimeter() // 14 - computed on access
    ()
```

Key differences between stored fields and properties:
- **Stored fields**: Evaluated once during construction, stored in memory
- **Properties**: Evaluated every time they're accessed, no storage

### Static Stored Fields

Static fields belong to the class itself, not individual instances:

```dovetail
class Config(name: String) =
    public let static defaultTimeout: Int32 = 30
    public let static maxRetries: Int32 = 3


function main(): Unit =
    Config.defaultTimeout  // 30 - accessed on class, not instance
    ()
```

Static fields are initialized once when the class is first loaded.

### Static Property Fields

Static properties are like static fields but computed each time they're accessed:

```dovetail
class Math(value: Int32) =
    public let static property pi: Float64 = 3.14159265359
    public let static property e: Float64 = 2.71828182846

    public function dummy(self): Int32 = 0

function main(): Unit =
    Math.pi  // 3.14159265359 - computed on access
    ()
```

### Mutable Fields

Use `let mutable` for fields that can be changed after construction:

```dovetail
class Counter(initial: Int32) =
    let mutable count: Int32 = initial

    public function increment(self): Unit = self.count = self.count + 1
    public function getCount(self): Int32 = self.count
```

### Chained Fields

Fields can depend on each other (in declaration order):

```dovetail
class Stats(base: Int32) =
    let doubled: Int32 = base * 2
    let quadrupled: Int32 = doubled * 2  // Uses earlier field

    public function getQuadrupled(self): Int32 = self.quadrupled
```

### Side Effects in Constructor Body

Any expression in the class body runs during construction:

```dovetail
class Logger(name: String) =
    let _ = debug("Creating logger: " ++ name)  // Runs at construction

    public function log(self, msg: String): Unit = debug(name ++ ": " ++ msg)
```

### Field Visibility

Fields can have visibility modifiers:

```dovetail
class Entity(id: Int32) =
    public let name: String = "entity"          // Accessible everywhere
    private let secret: String = "classified"   // Only within class
    let internal: String = "data"               // Package-level (default)

    public let property publicProp: Int32 = self.id * 2
    private let property privateProp: Int32 = self.id * 3

    public function dummy(self): Int32 = 0
```

---

## 9.4 Private Constructors

Use the `private` keyword after the class name to make the constructor private:

```dovetail
class Singleton private (value: Int32) =
    public function get(self): Int32 = self.value
    
    public function instance(): Singleton = Singleton(42)  // Only accessible here

function main(): Unit =
    // let s = Singleton(10)  // Error: constructor is private
    let s = Singleton.instance()  // OK - use smart constructor
    s.get()
    ()
```

Private constructors are useful for:
- Singleton patterns
- Factory patterns where validation is required
- Ensuring instances are created only through smart constructors

---

## 9.5 Mutable Fields

By default, class fields are immutable. Use `mutable` to allow modification:

```dovetail
class Counter(mutable value: Int32) =
    public function getValue(self): Int32 = self.value
    public function increment(self): Unit = self.value = self.value + 1
    public function add(self, amount: Int32): Unit = self.value = self.value + amount

function main(): Unit =
    let c = Counter(0)
    c.increment()
    c.increment()
    c.add(10)
    c.getValue()  // 12
    ()
```

You can mix mutable and immutable fields:

```dovetail
class Entity(id: Int32, mutable health: Int32) =
    public function getId(self): Int32 = self.id           // id is immutable
    public function getHealth(self): Int32 = self.health
    public function damage(self, amount: Int32): Unit =
        self.health = self.health - amount          // health is mutable
```

Attempting to assign to an immutable field results in a compile error.

---

## 9.6 Inheritance

Classes can extend other classes using `extends`:

```dovetail
class Animal(name: String) =
    public function getName(self): String = self.name

class Dog(name: String, breed: String) extends Animal(name) =
    public function getBreed(self): String = self.breed

function main(): Unit =
    let d = Dog("Rex", "German Shepherd")
    d.getName()   // "Rex" - inherited from Animal
    d.getBreed()  // "German Shepherd" - defined in Dog
    ()
```

The `extends` clause specifies:
1. The parent class name
2. Arguments to pass to the parent's constructor

Child classes inherit all methods from the parent and can access parent fields through inherited methods.

---

## 9.7 Abstract Classes

Abstract classes cannot be instantiated directly and can contain abstract methods:

```dovetail
abstract class Shape(name: String) =
    public function getName(self): String = self.name    // Concrete method
    public abstract function area(self): Int32           // Abstract method

class Square(name: String, side: Int32) extends Shape(name) =
    public override function area(self): Int32 = self.side * self.side  // Must implement

function main(): Unit =
    // let s = Shape("test")  // Error: cannot instantiate abstract class
    let sq = Square("square", 5)
    sq.area()  // 25
    ()
```

Key points:
- Use `abstract class` to define an abstract class
- Use `abstract function` to declare methods without implementation
- Abstract methods can only appear in abstract classes
- Concrete subclasses must implement all abstract methods

---

## 9.8 Sealed Abstract Classes

A `sealed abstract class` is an abstract class whose subclasses are restricted to the same package. This allows the compiler to know all possible subclasses and perform **exhaustiveness checking** on pattern matches — just like enums.

### Defining a Sealed Hierarchy

```dovetail
sealed abstract class Shape()
final class Circle(public radius: Float64) extends Shape()
final class Rectangle(public width: Float64, public height: Float64) extends Shape()
```

Rules for subclasses of a sealed class:
- Must be in the **same package**
- Must be either `final class` (leaf — cannot be extended) or `sealed abstract class` (intermediate — itself sealed)

### Exhaustive Pattern Matching

Because the compiler knows all subclasses, it can verify you've handled every case:

```dovetail
function area(s: Shape): Float64 =
    match s with
        case c: Circle => 3.14 * c.radius * c.radius
        case r: Rectangle => r.width * r.height
```

If you forget a case, the compiler reports an error:

```dovetail
function area(s: Shape): Float64 =
    match s with
        case c: Circle => 3.14 * c.radius * c.radius
        // Error: non-exhaustive match: missing case for Rectangle
```

You can still use a wildcard to catch remaining cases:

```dovetail
function describe(s: Shape): String =
    match s with
        case c: Circle => "circle"
        case _ => "other shape"
```

### Deep Sealed Hierarchies

Sealed abstract classes can form multi-level hierarchies. Matching on an intermediate sealed class covers all its leaf subclasses:

```dovetail
sealed abstract class Shape()
sealed abstract class Polygon() extends Shape()
final class Triangle(public base: Float64) extends Polygon()
final class Rectangle(public width: Float64) extends Polygon()
final class Circle(public radius: Float64) extends Shape()

function describe(s: Shape): String =
    match s with
        case p: Polygon => "polygon"   // Covers both Triangle and Rectangle
        case c: Circle => "circle"
```

### Sealed vs Enums

Both sealed classes and enums represent a fixed set of alternatives with exhaustive matching. Choose based on your needs:

- **Enums**: Best for simple discriminated unions where all variants share the same type parameters. Variants are lightweight (no methods or trait implementations).
- **Sealed classes**: Best when subclasses need their own type parameters, methods, trait implementations, or mutable state. Each subclass is a full class with its own capabilities.

---

## 9.9 Generic Classes

Classes can have type parameters:

```dovetail
class Box<T>(value: T) =
    public function get(self): T = self.value

function main(): Unit =
    let intBox = Box(42)
    let strBox = Box("hello")
    intBox.get()  // 42
    ()
```

### Multiple Type Parameters

```dovetail
class Pair<A, B>(first: A, second: B) =
    public function getFirst(self): A = self.first
    public function getSecond(self): B = self.second

function main(): Unit =
    let p = Pair(1, "one")
    p.getFirst()   // 1
    p.getSecond()  // "one"
    ()
```

### Mutable Generic Fields

```dovetail
class MutableBox<T>(mutable value: T) =
    public function get(self): T = self.value
    public function set(self, newValue: T): Unit = self.value = newValue

function main(): Unit =
    let box = MutableBox(10)
    box.set(20)
    box.get()  // 20
    ()
```

### Constrained Generic Classes

Use `where` clauses or inline constraints to restrict type parameters:

```dovetail
trait Countable =
    public function count(self): Int32

class Counter<T: Countable>(value: T) =
    public function getCount(self): Int32 = self.value.count()
```

Or with `where` clause:

```dovetail
class Wrapper<T>(value: T)
    where T: Printable
=
    public function fmt(self): String = self.value.format()
```

---

## 9.10 Implementing Traits for Classes

Generic classes can inherit trait method and property defaults. For methods with
their own type parameters, see
[Generic Trait Defaults](https://dovetaillang.org/book/advanced-generics.md#267-generic-trait-defaults).

Classes can implement traits in two ways:

### Inline Implementation

Use `implements` in the class declaration:

```dovetail
trait Speakable =
    public function speak(self): String

class Dog(name: String) implements Speakable =
    public function speak(self): String = "Woof"
    public function getName(self): String = self.name
```

### Multiple Traits

Use `and` to implement multiple traits:

```dovetail
trait Speakable =
    public function speak(self): String

trait Nameable =
    public function getName(self): String

class Dog(name: String) implements Speakable and Nameable =
    public function speak(self): String = "Woof"
    public function getName(self): String = self.name
```

### Combined with Inheritance

Classes can extend a parent and implement traits:

```dovetail
class Dog(name: String) extends Pet(name) implements Speakable and Comparable =
    public function speak(self): String = "Woof"
    public function compare(self, other: Dog): Int32 = 0
```

### External Implementation

You can also implement traits for classes externally:

```dovetail
trait Speakable =
    public function speak(self): String

class Dog(name: String) =
    public function bark(self): String = "Woof"

implement Speakable for Dog =
    public function speak(self): String = self.bark()
```

This is useful when:
- You don't own the class definition
- You want to add trait implementations later
- You're implementing traits from other packages

---

## 9.11 Extension Properties

Named extensions add computed properties without adding stored fields. Import the
extension explicitly, even when it is declared in the same package. Extension
properties use `property name(self): Type`, while class-body computed fields use
`let property name: Type`.

**Complete example (checked in CI)** — no extra dependencies:

<!-- book-example: {"name": "classes", "depends": []} -->
```dovetail
package classes

import classes.RectangleHelpers

class Rectangle(public width: Int32, public height: Int32) =
    public function dimensions(self): (Int32, Int32) = (self.width, self.height)

extension RectangleHelpers for Rectangle =
    property area(self): Int32 = self.width * self.height
    function scaled(self, factor: Int32): Rectangle =
        Rectangle(self.width * factor, self.height * factor)

function main(): Unit =
    let rectangle = Rectangle(3, 4)
    assert rectangle.area == 12
    assert rectangle.scaled(2).area == 48

test "extension properties compute from public fields" = main()
```

Properties are evaluated on access. Extensions follow normal visibility rules and
cannot use private construction to bypass a type's smart constructors. Records
and enums can also be extended; see [Extension Methods](https://dovetaillang.org/book/type-system.md#69-extension-methods).

---

## 9.12 Extension Methods for Classes

`RectangleHelpers` above defines both a property and a method. Call its method with
ordinary receiver syntax, such as `rectangle.scaled(2)`, after importing the named
extension. An extension does not change the class's inheritance hierarchy.

Generic extensions declare their parameters on the extension name:

```dovetail
class Container<T>(value: T) =
    function getValue(self): T = self.value

extension ContainerHelpers<T> for Container<T> =
    function map<U>(self, transform: T => U): Container<U> =
        Container(transform(self.getValue()))
```

Import `yourPackage.ContainerHelpers` at the call site. See
[Advanced Generics](https://dovetaillang.org/book/advanced-generics.md#261-generic-extensions) for bounds.

---

## 9.13 Visibility Modifiers

Control access to classes, fields, and methods with visibility modifiers:

### Class Visibility

```dovetail
public class PublicPoint(x: Int32, y: Int32) =
    function getX(self): Int32 = self.x

private class PrivateHelper(value: Int32) =
    function get(self): Int32 = self.value

internal class InternalUtil(data: String) =  // Default visibility
    function getData(self): String = self.data
```

### Field Visibility

```dovetail
class Entity(
    public id: Int32,           // Accessible everywhere
    private secret: String,     // Only within this class
    internal data: Int32        // Within this package; fields default to private
) =
    function getId(self): Int32 = self.id
    function getSecret(self): String = self.secret  // OK - inside class
```

Private fields are not accessible outside the class:

```dovetail
function main(): Unit =
    let e = Entity(1, "secret", 42)
    e.id      // OK - public
    // e.secret  // Error - private field
    0
    ()
```

### Method Visibility

Class fields and methods default to `private`. Expose operations with `public` or
`internal` explicitly. This differs from top-level declarations, which default to
`internal`.

```dovetail
class Calculator(value: Int32) =
    private function helper(self): Int32 = self.value * 2
    public function compute(self): Int32 = self.helper() + 1
    internal function packageHelper(self): Int32 = 0  // Explicit package visibility
```

### Combining with Mutable

Visibility can be combined with mutable:

```dovetail
class Counter(private mutable count: Int32) =
    function increment(self): Unit = self.count = self.count + 1
    function getCount(self): Int32 = self.count
```

---

## 9.14 Classes vs Records

| Feature | Class | Record |
|---------|-------|--------|
| Methods | Defined in body | Via associated modules or named extensions |
| Mutability | Mutable fields supported | Always immutable |
| Inheritance | Supported | Not supported |
| Abstract | Supported | Not supported |
| Identity | Reference identity | Value equality |
| Use case | Stateful objects | Pure data |

**When to use classes:**
- You need mutable state
- You need inheritance hierarchies
- You're modeling entities with identity
- You need encapsulation with private fields

**When to use records:**
- You're modeling pure data
- You want value semantics
- You don't need inheritance
- Immutability is preferred

---

## 9.15 Class Identity

`ClassIdentity.equals` asks whether two references name the same instance, independently of its fields or any `Equatable` implementation:

```dovetail
class IdentityCounter(public mutable value: Int32)

function checkIdentity(): Unit =
    let first = IdentityCounter(1)
    let alias = first
    let second = IdentityCounter(1)
    assert ClassIdentity.equals(first, alias)
    assert !ClassIdentity.equals(first, second)
    let hash = ClassIdentity.hash(first)
    first.value = 2
    assert ClassIdentity.equals(first, alias)
    assert ClassIdentity.hash(alias) == hash
```

Both functions are available for every class, including generic classes and abstract base references. Upcasts preserve identity and the hash. To compare related types explicitly, use `ClassIdentity.equals<Base>(left, right)`. Unrelated classes have no implicit common object type for this call.

Every class instance reserves one hidden hash slot. Its value is assigned on the first `ClassIdentity.hash` call and stays fixed for that object's lifetime. Equality does not initialize the hash. Hashes may collide: equal hashes do not prove that objects are identical. They are not persistent identifiers and must not be used as unique handles.

These primitives require no annotation. Classes still need explicit `Equatable` and `Hashable` implementations to use identity semantics through those traits; see [Identity Equality and Hashing](https://dovetaillang.org/book/traits.md#identity-equality-and-hashing). Generic functions can call both primitives under `where T: class`.

## Summary

- **Class Definitions**: Combine constructor parameters with methods using `class Name(fields) = methods`
- **Instance Methods**: Take `self` parameter; **Static Methods**: No `self`, called on class
- **Smart Constructors**: Use static methods to provide alternative ways to create instances with validation
- **Class Body Fields**: Use unified `let` syntax for stored fields, properties, static fields, and static properties
- **Property Fields**: Use `let property` for computed getters evaluated on each access
- **Static Fields**: Use `let static` for class-level fields; `let static property` for class-level computed getters
- **Private Constructors**: Use `class Name private (fields)` to restrict instantiation to smart constructors
- **Mutable Fields**: Use `mutable` keyword to allow field modification
- **Inheritance**: Use `extends Parent(args)` to inherit from another class
- **Abstract Classes**: Use `abstract class` and `abstract function` for unimplemented methods
- **Sealed Abstract Classes**: Use `sealed abstract class` to restrict subclasses to the same package with exhaustive pattern matching
- **Generic Classes**: Type parameters with `class Name<T>`, constraints with `where T: Trait`
- **Trait Implementation**: Inline with `implements Trait` or external with `implement Trait for Class`
- **Extension Properties**: Add computed properties with `property name(self): Type` in named extensions
- **Extension Methods**: Add methods to classes with `extension Helpers for ClassName`
- **Visibility**: Control access with `public`, `private`, `internal` on classes, fields, methods, and properties


---

# Part 10: Error Handling

Source: https://dovetaillang.org/book/error-handling/


Dovetail takes a different approach to error handling than many mainstream languages. Instead of exceptions and try/catch blocks, Dovetail uses **values** to represent errors. This makes error handling explicit, composable, and checked by the compiler.

---

## 10.1 No Exceptions

In many languages, functions can throw exceptions at any point, and callers may or may not handle them. This leads to hidden control flow and runtime surprises.

Dovetail has **no exceptions**. Instead, it provides two types for representing the absence of a value or the possibility of failure:

- **`Option<T>`** — a value that may or may not exist
- **`Result<T, E>`** — an operation that may succeed with `T` or fail with `E`

Both are regular enum types defined in the prelude. There's nothing magical about them — they follow the same rules as any other enum. The compiler ensures you handle both cases.

**Benefits of errors-as-values:**

- **Explicit** — the function signature tells you whether it can fail
- **Composable** — chain operations with methods like `map`, `andThen`, and `try`/`orReturn`
- **Compiler-checked** — you can't accidentally ignore an error case in a `match`

---

## 10.2 Option Type

### Definition

`Option<T>` represents a value that may or may not be present:

```dovetail
public enum Option<T> =
    Some(T)
    None
```

### When to Use Option

Use `Option` when the absence of a value is a **normal, expected** situation — not an error:

- Looking up a key in a map
- Finding the first element that matches a condition
- Parsing an optional configuration field

### Creating Option Values

```dovetail
let found: Option<Int32> = Some(42)
let missing: Option<Int32> = None
```

### Pattern Matching on Option

The most fundamental way to work with `Option` is pattern matching:

```dovetail
function describe(maybe: Option<Int32>): String =
    match maybe with
        case Some(value) => "Found: $value"
        case None => "Nothing here"
```

### Useful Methods

**`or`** — unwrap the value or use a default:

```dovetail
let x: Option<Int32> = Some(5)
let y: Option<Int32> = None

assert x.or(0) == 5
assert y.or(0) == 0
```

**`expect`** — unwrap or panic with a message:

```dovetail
let x: Option<Int32> = Some(42)
let value = x.expect("value must exist")
assert value == 42
```

**`require`** — unwrap or panic with a default message:

```dovetail
let x: Option<Int32> = Some(7)
assert x.require == 7
```

**`isSome` / `isNone`** — test which variant:

```dovetail
let x: Option<Int32> = Some(1)
assert x.isSome
assert x.isNone == false
```

**`map`** — transform the inner value if present:

```dovetail
let x: Option<Int32> = Some(3)
let doubled = x.map(v => v * 2)   // Some(6)

let y: Option<Int32> = None
let result = y.map(v => v * 2)    // None
```

**`andThen`** — chain operations that themselves return `Option`:

```dovetail
function half(x: Int32): Option<Int32> =
    if x % 2 == 0 then Some(x / 2) else None

let result = Some(10).andThen(half)  // Some(5)
let failed = Some(3).andThen(half)   // None
```

**`filter`** — keep the value only if a predicate holds:

```dovetail
let x = Some(10).filter(v => v > 5)   // Some(10)
let y = Some(3).filter(v => v > 5)    // None
```

### Converting: toResult

Convert an `Option` to a `Result` by providing an error value for the `None` case:

```dovetail
let x: Option<Int32> = Some(42)
let r = x.toResult("not found")   // Ok(42)

let y: Option<Int32> = None
let s = y.toResult("not found")   // Error("not found")
```

---

## 10.3 Result Type

### Definition

`Result<T, E>` represents an operation that can succeed or fail:

```dovetail
public enum Result<T, E> =
    Ok(T)
    Error(E)
```

### When to Use Result

Use `Result` when an operation can **fail** and you want the caller to handle the failure:

- Parsing user input
- Reading from a file
- Validating data
- Network requests

### Creating Result Values

```dovetail
let success: Result<Int32, String> = Ok(42)
let failure: Result<Int32, String> = Result.error("something went wrong")
```

`Ok(value)` and `Error(error)` are variant constructors. The module also offers
`Result.ok(value)` and `Result.error(error)` helpers.

### Pattern Matching on Result

```dovetail
function describe(result: Result<Int32, String>): String =
    match result with
        case Ok(value) => "Success: $value"
        case Error(msg) => "Failed: $msg"
```

### Useful Methods

**`or`** — unwrap the success value or use a default:

```dovetail
let ok: Result<Int32, String> = Ok(5)
let err: Result<Int32, String> = Result.error("oops")

assert ok.or(0) == 5
assert err.or(0) == 0
```

**`expect`** — unwrap or panic with a message:

```dovetail
let r: Result<Int32, String> = Ok(42)
assert r.expect("must succeed") == 42
```

**`require`** — unwrap or panic with a default message:

```dovetail
let r: Result<Int32, String> = Ok(7)
assert r.require == 7
```

**`isOk` / `isError`** — test which variant:

```dovetail
let ok: Result<Int32, String> = Ok(1)
assert ok.isOk
assert ok.isError == false
```

**`map`** — transform the success value:

```dovetail
let r: Result<Int32, String> = Ok(3)
let doubled = r.map(v => v * 2)   // Ok(6)
```

**`mapError`** — transform the error value:

```dovetail
let r: Result<Int32, String> = Result.error("fail")
let wrapped = r.mapError(e => "wrapped: $e")  // Error("wrapped: fail")
```

**`andThen`** — chain operations that return `Result`:

```dovetail
function parseAge(input: String): Result<Int32, String> =
    // ... parsing logic

function validateAge(age: Int32): Result<Int32, String> =
    if age >= 0 then Ok(age) else Result.error("age must be non-negative")

let result = parseAge("25").andThen(validateAge)
```

### Converting: toOption

Convert a `Result` to an `Option`, discarding the error information:

```dovetail
let ok: Result<Int32, String> = Ok(42)
assert ok.toOption().isSome       // Some(42)

let err: Result<Int32, String> = Result.error("fail")
assert err.toOption().isNone      // None
```

---

## 10.4 Railway-Oriented Programming

### The Problem

When chaining multiple operations that can fail, pattern matching quickly becomes deeply nested:

```dovetail
function processUser(id: Int32): Result<String, String> =
    match lookupUser(id) with
        case Error(e) => Result.error(e)
        case Ok(user) =>
            match validateUser(user) with
                case Error(e) => Result.error(e)
                case Ok(valid) =>
                    match formatUser(valid) with
                        case Error(e) => Result.error(e)
                        case Ok(output) => Ok(output)
```

This is sometimes called the "pyramid of doom." Each level of nesting adds visual noise without adding meaning.

### try and orReturn

Dovetail provides two equivalent syntactic forms to flatten this pattern:

- **`try expr`** — prefix syntax
- **`expr.orReturn`** — postfix syntax

Both do the same thing: **unwrap the success value, or early-return the error** from the enclosing function.

The example above becomes:

```dovetail
function processUser(id: Int32): Result<String, String> =
    let user = try lookupUser(id)
    let valid = try validateUser(user)
    formatUser(valid)
```

Or using the postfix form:

```dovetail
function processUser(id: Int32): Result<String, String> =
    let user = lookupUser(id).orReturn
    let valid = validateUser(user).orReturn
    formatUser(valid)
```

### How They Work

When you write `try expr` (or `expr.orReturn`):

1. The expression is evaluated — it must produce an `Option` or `Result`
2. If it's `Some(value)` or `Ok(value)`, the value is unwrapped and execution continues
3. If it's `None` or `Error(e)`, the enclosing function **immediately returns** with the failure value

### Return Type Compatibility

The enclosing function's return type must be compatible with the early return:

- If you `try` a `Result<T, E>`, the function must return `Result<_, E>` (same error type)
- If you `try` an `Option<T>`, the function must return `Option<_>`

```dovetail
// Works: both return Result<_, String>
function process(): Result<Int32, String> =
    let x = try getResult()   // getResult(): Result<Int32, String>
    Ok(x + 1)

// Works: both return Option<_>
function find(): Option<Int32> =
    let x = try lookup()      // lookup(): Option<Int32>
    Some(x + 1)
```

### Chaining Multiple Operations

You can freely mix `try`/`orReturn` with regular code in a single function:

```dovetail
function validateAndProcess(input: String): Result<Output, String> =
    let parsed = try parse(input)
    let validated = try validate(parsed)
    let enriched = enrich(validated)   // this one can't fail
    let result = try save(enriched)
    Ok(result)
```

### Chaining After orReturn

Because `orReturn` is a postfix operator, you can chain further operations directly on the unwrapped value — accessing tuple fields, calling methods, or accessing properties:

```dovetail
function getUser(): Result<(String, Int32), String> = Ok(("Alice", 30))

function getUserName(): Result<String, String> =
    let name = getUser().orReturn._0
    Ok(name)
```

```dovetail
function getConfig(): Result<Option<Int32>, String> = Ok(Some(42))

function process(): Result<Bool, String> =
    let hasSetting = getConfig().orReturn.isSome
    Ok(hasSetting)
```

This is one of the advantages of the postfix `orReturn` form over the prefix `try` — it reads naturally left-to-right without needing parentheses.

### Complete Example

Here's a multi-step validation pipeline:

```dovetail
function validateEmail(email: String): Result<String, String> =
    if email.length == 0 then
        Result.error("email cannot be empty")
    else if email.contains("@") == false then
        Result.error("email must contain @")
    else
        Ok(email)

function validateAge(age: Int32): Result<Int32, String> =
    if age < 0 then
        Result.error("age cannot be negative")
    else if age > 150 then
        Result.error("age is unrealistic")
    else
        Ok(age)

function createProfile(name: String, email: String, age: Int32): Result<Profile, String> =
    let validEmail = try validateEmail(email)
    let validAge = try validateAge(age)
    Ok(Profile { name = name; email = validEmail; age = validAge })
```

If any validation fails, `createProfile` immediately returns the first error. No nesting required.

---

## 10.5 Panics and Assertions

### Panic

The `panic` expression signals a defect. In synchronous application code it
terminates execution; tests can expect it with `@panics`. Async execution represents
defects through its cause channel, as described in [Async Programming](https://dovetaillang.org/book/async.md):

```dovetail
panic "something went terribly wrong"
```

Panics are for truly unexpected situations — bugs, violated invariants, or states that "should never happen." They are **not** for expected error conditions.

### Assert

The `assert` expression checks a condition and panics if it's false:

```dovetail
assert x > 0
assert list.length == expectedLength
```

Assertions are commonly used in tests and to check invariants during development.

### When to Use Panics vs Result

| Use `panic`/`assert` when... | Use `Result` when... |
|-------------------------------|----------------------|
| A bug has been detected | An operation can legitimately fail |
| An invariant is violated | User input might be invalid |
| "This should never happen" | A resource might be unavailable |
| In tests | The caller should decide how to handle failure |

### expect and require — Bridging Option/Result to Panics

Sometimes you're certain a value exists or an operation succeeded, and a missing value would be a bug. The `expect` and `require` methods let you unwrap with a panic:

```dovetail
// With a custom message
let config = loadConfig().expect("config file must exist")

// With a default message
let value = maybeValue.require
```

Use these sparingly. In production code, prefer `or`, `map`, or `try`/`orReturn` to handle failures gracefully. Reserve `expect`/`require` for cases where failure genuinely indicates a programming error.

---

## Summary

- Dovetail uses **errors as values** — no exceptions, no hidden control flow
- **`Option<T>`** represents optional values (`Some` or `None`)
- **`Result<T, E>`** represents operations that can fail (`Ok` or `Error`)
- Both types provide methods for safe access: `or`, `expect`, `require`, `isSome`/`isNone`, `isOk`/`isError`
- **`map`** and **`andThen`** transform values without unwrapping
- **`try`** (prefix) and **`orReturn`** (postfix) enable railway-oriented programming — flat, readable chains of fallible operations
- **`toResult`** and **`toOption`** convert between the two types
- **`panic`** and **`assert`** are for unrecoverable errors and invariant checking
- **`expect`** and **`require`** bridge `Option`/`Result` to panics when failure is a bug

### Discarded results

An intermediate expression normally discards its value. Dovetail warns when
that value is a `Result`, because a failure could go unnoticed:

```dovetail
parseNumber(text)  // Warning if this returns Result
()
```

Handle the result, propagate it with `try` in a compatible function, or return
it. If ignoring either outcome is deliberate, write `let _ = parseNumber(text)`.
The initializer still evaluates normally. This acknowledgement applies only to
the final value of the initializer;
intermediate discarded results inside it still warn.

These warnings appear during checking, compilation, and in the editor, and do
not fail compilation. Type aliases retain the warning. Ordinary intermediate
values, such as counters and builder chains, still need no acknowledgement.
The check does not track whether a named binding is eventually used or inspect
values hidden inside containers or erased types.


---

# Part 11: Packages and Modules

Source: https://dovetaillang.org/book/packages/


Dovetail organizes code into **packages** and **modules**. Every source file declares its package, and you bring types and functions from other packages in with **imports**. The compiler enforces that package names match the directory structure and that dependencies form a directed acyclic graph—no circular imports.

---

## 11.1 Package Declaration

### Every File Has a Package

Every Dovetail source file must start with a **package declaration**. This identifies which package the file belongs to:

```dovetail
package hello

function main() =
    debug("Hello, World!")
```

For a library with a deeper structure:

```dovetail
package com.example.users

record User =
    name: String
    age: Int32
```

The package path uses **dot notation**. Each segment typically corresponds to a directory: `com.example.users` matches a path like `com/example/users/` under the project’s source root.

### Package Must Match Directory Structure

The compiler enforces that the declared package matches the file’s location. If your project’s root package is `com.example.myapp`, then:

- `src/main.dove` → `package com.example.myapp`
- `src/utils/helpers.dove` → `package com.example.myapp.utils`

This keeps the codebase predictable: you can infer the package from the path and the path from the package.

### Relationship to Projects and `Dovetail.toml`

When you use the `dovetail` CLI, each **project** in the workspace has a **root package** defined in `Dovetail.toml`:

```toml
compiler-version = "0.1.4"

[[project]]
name = "api"
root_package = "com.example.api"
packages = ["."]
```

All source files under that project’s `src/` directory belong to packages under that root. For example, `api/src/handlers.dove` would declare `package com.example.api`, and `api/src/auth/validate.dove` would declare `package com.example.api.auth`.

Single-file compilation with `dovetail` does not use `Dovetail.toml`; you still declare a package at the top of the file (e.g. `package myapp`).

### Module file shorthand

Instead of writing `package` and then an inline `module Name = ...`, you can make the **entire file** a module by starting with:

```dovetail
module package_path.ModuleName
```

or, for a generic type, **`module package_path.TypeName<T>`** (e.g. `module standard.prelude.Array<T>`). The rest of the file is the module body; the effective package is `package_path`. The **kind** of module (standalone vs module for a type) is determined by whether that name is an existing type in the package. Different files in a package may define different modules. A type and its associated same-name module may also be declared in separate files of that package. See [Part 6: Type System — Modules](https://dovetaillang.org/book/type-system.md#68-modules) for the two kinds of modules and what each may contain.

---

## 11.2 Imports

### Importing Types and Functions

To use a type or function from another package, add an **import** after the package declaration. Imports come at the top of the file, one per line:

```dovetail
package api

import users.User
import users.Email
import users.validate
import http.Request
import http.Response

function handleGetUser(req: Request): Response =
    let user = User.find(req.params.id) orReturn
    Ok(user.toJson())
```

You import by **qualified name**: the package path followed by the declaration name. There are no wildcard imports (`import users.*` is not allowed), so it’s always clear where each name comes from.

### Aliased Imports

If a name would clash with a local type or you prefer a shorter name, use an alias:

```dovetail
package api

import users.User as AppUser
import http.Request as HttpRequest

function handle(req: HttpRequest): Unit =
    let u: AppUser = AppUser.fromRequest(req)
    ...
```

The alias is used everywhere in that file instead of the original name.

### Full Package Paths

For packages with multiple segments, use the full path in the import:

```dovetail
package com.example.myapp

import com.example.core.types.Id
import com.example.core.utils.formatDate
```

The compiler resolves imports using the packages exposed by the current project and its dependencies (as specified in `Dovetail.toml` for workspace builds).

### Modules and extension methods across packages

**Same package:** Instance methods on a type in the same package come from a **module for that type** (a module with the same name as the type, if the package defines one). You do not need to import the module to use instance members — they are available whenever the type is in scope. Static members and globals require the module to be in scope (same package or imported). For a generic type you must supply type arguments when accessing statics or globals: e.g. `Array<Int32>.empty`, `Array<Int32>.defaultCapacity`. See [Modules](https://dovetaillang.org/book/type-system.md#68-modules).

**Cross package:** To add methods to a type from another package, use a **named extension** and **import it explicitly**:

```dovetail
// File: json/encoders.dove
package json
import users.User

extension UserJson for User =
    function toJson(self): Json = ...
```

Consumers must import the extension by name:

```dovetail
package api

import users.User
import json.UserJson

function serialize(u: User): Json =
    u.toJson()   // UserJson is in scope via import
```

Trait implementations for types from another package follow the **orphan rule** (see Part 8): you may only implement a trait if your package defines either the trait or the type. When the trait is in your package and the type is imported, the implementation is discovered when the trait is used; you don’t import the implementation itself.

---

## 11.3 Visibility

Declarations can be restricted by **visibility**. This controls whether other packages (or other files in the same package) can see a type, function, or member.

### Visibility Levels

| Modifier   | Meaning |
|-----------|--------|
| `public`  | Visible from any package that depends on this package. |
| `internal`| Visible within the same **package** only. This is the **default**. |
| `private` | Visible within the declaring **file** only. |
| `protected`| Visible within the declaring class and its subclasses (see Part 9). |

If you don't write a modifier, the declaration is `internal` — visible to the rest of its own package and to nothing else. That makes each package's public surface an explicit choice, which is what lets you use packages as architectural layers.

### Making Declarations Public

Use `public` when you want to expose a type or function to other packages:

```dovetail
package math

public function add(a: Int32, b: Int32): Int32 =
    a + b

public record Point =
    x: Int32
    y: Int32
```

Without `public`, `add` and `Point` would only be visible inside the `math` package.

### Type Visibility and Private Construction

A leading `private` hides a declaration from other files. A `private` after a type's name restricts operations on its values. These are separate choices:

```dovetail
package users

public newtype Email private = String

module Email =
    public function parse(s: String): Result<Email, String> =
        if s.contains("@") then
            Ok(Email(s))
        else
            Error("Invalid email")

    public function text(self): String = self.value
```

Other packages can import `users.Email`, call `Email.parse`, and use `email.text()`. Direct construction, `.value`, and unwrapping patterns require `module Email` in package `users`. Another function in `users`, a trait implementation, an extension, or a same-named module in another package has no such privilege.

For `public record Account private = ...` and `public enum Status private = ...`, callers can inspect fields and match patterns. Only their associated modules in the defining package can construct values; record `with` updates have the same restriction. Put the modifier after any type parameters and before any `where` clause. See [private records](https://dovetaillang.org/book/type-system.md#private-construction), [private enums](https://dovetaillang.org/book/type-system.md#private-construction-of-enums), and [private newtypes](https://dovetaillang.org/book/type-system.md#private-newtypes).

### Internal Visibility

`internal` is the default, so most declarations are already package-scoped: visible to every file of their own package, invisible everywhere else. Write it explicitly when you want that intent to be obvious. Use `private` when a helper should not even escape the file it is declared in.

---

## 11.4 No Circular Dependencies

### Dependency Direction

Packages must not depend on each other in a cycle. If package **A** imports from package **B**, then **B** must not import from **A**. The dependency graph must be a **directed acyclic graph (DAG)**.

The compiler enforces this. You’ll get an error if you introduce a circular dependency.

### Why No Cycles?

- **Compilation order:** The compiler processes packages in dependency order. Cycles would make that order undefined.
- **Clear boundaries:** Acyclic dependencies encourage a clear layering of your code (e.g. core → domain → api → app).
- **Faster builds:** The build system can schedule work along the DAG; cycles would complicate caching and parallelization.

### Project-Level Dependencies

In a workspace, dependencies are declared per **project** in `Dovetail.toml`:

```toml
compiler-version = "0.1.4"

[[project]]
name = "core"
root_package = "com.example.core"
packages = ["."]

[[project]]
name = "api"
root_package = "com.example.api"
depends = ["core"]
packages = ["."]

[[project]]
name = "myapp"
root_package = "com.example.myapp"
depends = ["core", "api"]
packages = ["."]
```

Here, `core` has no project dependencies; `api` depends on `core`; `myapp` depends on both. Packages under `api` can import from packages under `core`, and packages under `myapp` can import from both. The reverse is not allowed: `core` cannot depend on `api` or `myapp`.

### Resolving Cycles

If you discover a cycle, you usually need to:

1. **Extract shared code** into a new package that both sides depend on (e.g. move common types into `core`).
2. **Invert the dependency** (e.g. use callbacks or traits so that the lower layer doesn’t reference the higher layer by type).
3. **Restructure** so that the dependency flows in one direction (e.g. merge two packages or split one).

---

## 11.5 GitHub Dependencies

Projects can use libraries from public or private Git repositories, including repositories containing several Dovetail projects. Declare each repository and revision once in `Dovetail.toml`, select the projects to make available, and use their names in a local project's `depends` list.

### Declare a Repository and Select Projects

The following example imports two projects from one repository. Replace the example URL and tag with those of your library:

```toml
compiler-version = "0.1.4"

[[dependencies]]
git = "https://github.com/acme/database.git"
tag = "v1.2.0"
projects = ["postgres", "sqlite"]

[[project]]
name = "api"
root_package = "com.example.api"
packages = ["."]
depends = ["postgres", "sqlite"]
```

Use `[[dependencies]]` with **double brackets** for each repository declaration. It has no user-assigned section name. The `projects` list selects project names from the repository's `Dovetail.toml`; those names are available throughout the declaring manifest. Each local project chooses which ones it uses through `depends`, just as it does for local sibling projects.

The compiler resolves the complete transitive dependency tree. If `postgres` depends on another project in its own repository or on a project from another Git repository, Dovetail resolves that dependency using the library's manifest. Your application does not need to repeat those declarations. Cycles remain errors, including cycles spanning repositories.

### Pin the Compiler and Library Revision

Every manifest must declare `compiler-version`. Run `dovetail --version` to find your binary's version; the examples here assume `0.1.4`. The workspace and every reachable dependency manifest must require that exact version. Build, check, run, and test reject a root version mismatch before fetching dependencies. Editor analysis performs the same compatibility checks.

The compiler version also pins the bundled prelude. Dependencies use that prelude, and cannot supply a conflicting replacement. A published tag without `compiler-version` cannot be used until its publisher adds the field in a new revision.

Choose at most one revision selector per repository declaration:

| Field | Selects |
|-------|---------|
| `tag = "v1.2.0"` | A Git tag |
| `branch = "1.2"` | A Git branch named `1.2` |
| `rev = "<commit-sha>"` | A specific Git commit |

Omitting all three initially selects the repository's default branch. Dovetail records the resolved full commit in `Dovetail.lock`; normal builds keep that commit even if the branch or tag moves upstream. These selectors are Git references, not semantic-version ranges.

For a repository with a manifest below its root, add `manifest = "libraries/Dovetail.toml"` to the repository declaration. The selected project names and their directories are resolved relative to that manifest.

### Keep Package Imports Unchanged

Repository project names select dependencies; source imports use the library's declared package names. For example, if the `postgres` project exposes a public `Connection` type in `acme.postgres`, your application imports it as:

```dovetail
package com.example.api

import acme.postgres.Connection
```

Neither the repository URL nor its revision appears in the import. The library still controls which declarations are `public`.

### Aliases and Multiple Versions

By default, an imported project keeps its original name. Use `{ project, alias }` to choose another name in the consuming manifest. For example, add this top-level declaration alongside the first one to make an older revision available as `postgres-1.1`:

```toml
[[dependencies]]
git = "https://github.com/acme/database.git"
tag = "v1.1.0"
projects = [{ project = "postgres", alias = "postgres-1.1" }]
```

A local project can then select it with `depends = ["postgres-1.1"]`. Aliases are scoped to the manifest declaring them and must not collide with local project names or other imported aliases. They do not rename package FQNs or source imports; this is different from an `import ... as ...` alias, which renames a declaration within one source file.

Different local targets may use different revisions. However, two distinct providers of the same package FQN cannot coexist in one target's dependency tree, including through transitive dependencies. Adding both Postgres revisions to one target produces an error with the conflicting dependency paths. A diamond that reaches the same resolved project twice is deduplicated.

### Fetch, Build, and Update

A normal `dovetail build` fetches missing dependencies as needed. You can also manage them explicitly:

```bash
dovetail deps fetch
dovetail build --locked
dovetail check --locked --offline

dovetail deps update postgres
dovetail deps update
```

- `deps fetch` materializes declared selections and their transitive dependencies, including selections not yet used by a local target.
- `--locked` requires `Dovetail.lock` to remain unchanged. Use it after resolving dependencies to detect changes that would require a new lockfile.
- `--offline` prevents network fetching. Dependencies must already be available locally.
- `deps update postgres` updates the repository declaration containing that name or alias. All projects selected by that declaration move together, so in the first example both `postgres` and `sqlite` update.
- `deps update` updates dependencies across the graph.

Updating re-resolves the declared Git selector. To switch from `v1.2.0` to a newer release tag, edit `tag` in `Dovetail.toml` and run `dovetail deps fetch` or build again.

**Commit `Dovetail.lock` and ignore `.dovetail/`.** Dovetail shares source checkouts at `.dovetail/deps/<repository-digest>/<full-commit>/` across aliases and project selections. The root workspace's lockfile controls resolution; a fetched library's lockfile does not override it.

Workspace builds and tests select local projects. Remote projects supply source and assets without becoming independent output targets, and their tests are not run implicitly.

### Private Repositories, Assets, and Editor Navigation

Private repositories use the installed Git executable and your configured HTTPS credential helper or SSH agent. An SSH declaration can use `git = "git@github.com:acme/private-library.git"`. Configure access through Git; keep credentials out of `Dovetail.toml`. Editor fetching is noninteractive.

A dependency can carry prebuilt WebAssembly components, resources, and macro scripts, including transitively. Commit the actual artifact files in Git. Automatic Git LFS hydration, submodule fetching, native build scripts, and release-asset downloading are not supported.

The language server resolves the same dependency graph as the CLI. Go-to-definition opens the checked-out source, and semantic requests use the consuming project's dependency revision. Fetched files remain available for offline navigation and are read-only dependency sources. Generated component bindings are navigable under `.dovetail/generated/`.

### Select Standard Libraries with One Tag

Use top-level `standard-tag` to make all standard library projects available at one revision:

```toml
compiler-version = "0.1.4"
standard-tag = "<tag>"

[[project]]
name = "api"
root_package = "com.example.api"
packages = ["."]
depends = ["standard-collection", "standard-json"]
```

Replace `<tag>` with a tag whose manifest declares the matching compiler version. Currently this shorthand uses `https://github.com/somdoron/dovetail.git`. It exposes projects rooted at `standard` or `standard.*`, retaining their actual project names such as `standard-json`, while excluding `standard.prelude`. Each local project still selects the libraries it needs through `depends`.

The [Git dependencies design](https://github.com/somdoron/dovetail/blob/main/docs/github-dependencies-design.md) describes the resolver and compatibility rules in more detail.

---

## Summary

- Every file starts with a **package** declaration; the package path must match the directory structure.
- Use **imports** to bring in types and functions from other packages; one import per line, no wildcards. Use **aliased imports** when names clash or you want a shorter name.
- **Named extensions** must be explicitly imported, including within the same package. Trait implementations follow their own visibility and coherence rules.
- **Visibility** is controlled by `public`, `private`, and `internal` so you can hide implementation details and expose a clear API.
- **Git dependencies** are declared once per repository and revision, selected through project `depends`, and pinned in `Dovetail.lock`. Package imports keep their original names.
- **Circular dependencies** are disallowed; the compiler enforces a DAG of package (and project) dependencies, which keeps builds and design predictable.

In the next part, we’ll look at async programming and the `await` operator.


---

# Part 12: Async Programming

Source: https://dovetaillang.org/book/async/


Dovetail models asynchronous work as **values**, not as a hidden runtime feature bolted onto regular functions. An asynchronous computation is a description of work to be performed — it doesn't run until something explicitly drives it.

This chapter covers the `Async` type, how to write async functions, the `await` operator, how to run an async program from `main`, and how to compose work in parallel.

---

## 12.1 The Async Type

`Async<T, E>` describes a computation that, when run, eventually produces either a value of type `T` or fails with an error of type `E`.

```dovetail
let greeting: Async<String, Never> = Async.succeed("hello")
let broken: Async<Int32, String> = Async.fail("not found")
```

The two type parameters are independent. `T` is the success type; `E` is the typed error channel. A computation that cannot fail uses `Never` for `E` — this is common enough to have a dedicated alias:

```dovetail
type Task<T> = Async<T, Never>
```

`Async` values are inert. Constructing one does no work — it merely builds a description. Work only happens when something runs the value (see 12.4).

### Constructing Async Values

The two primitive constructors are `Async.succeed` and `Async.fail`:

```dovetail
let ok: Async<Int32, Never> = Async.succeed(42)
let bad: Async<Int32, String> = Async.fail("oops")
```

Most async values, however, come from async functions (12.2) or from library calls such as `Async.sleep`, file I/O, or network operations.

### Errors, Panics, and Interruption

A failure in an async program is more than just a typed error. The runtime distinguishes three kinds of failure, captured by `Cause<E>`:

- **`Failed(e)`** — a typed error of type `E` (the same channel as `Async.fail`)
- **`Panicked(message)`** — an async defect, such as `Async.failPanic(message)`; a language-level `panic` or failed `assert` instead aborts execution with a Wasm trap
- **`Interrupted`** — the fiber was cancelled (see 12.5)

Most code only cares about typed failures; the other variants surface through panic handlers and structured-concurrency cancellation.

---

## 12.2 Async Functions

An async function is declared with the `async` keyword before `function`. Inside its body, `await` is allowed.

```dovetail
async function fetchGreeting(): Async<String, Never> =
    await Async.succeed("Hello, World!")
```

The body of an async function returns the **success type** (`T`), not an `Async<T, E>` value. To take a value out of an existing async value, use `await`; to propagate a typed failure, `await Async.fail(...)`.

**The return type is required.** The compiler does not infer the return type of an async function — you must write `: Async<T, E>` explicitly.

```dovetail
async function add(a: Int32, b: Int32): Async<Int32, Never> =
    await Async.succeed(a + b)

async function lookup(key: String): Async<String, NotFound> =
    if key == "answer" then
        await Async.succeed("42")
    else
        await Async.fail(NotFound(key))
```

### Async Closures

`async` may also be applied to lambdas. The return type is still required:

```dovetail
let f: (Int32) => Async<Int32, Never> =
    async (x: Int32): Async<Int32, Never> => await Async.succeed(x * 2)
```

### Async Expressions

Use `async do` to construct a deferred computation directly inside an expression:

```dovetail
let program = async do
    let first = await Async.succeed(20)
    let second = await Async.succeed(22)
    first + second
```

The entire body is deferred, including ordinary statements before the first
`await`. Its final expression supplies the success value. Running the value
again executes the body again, with fresh local variables. Captures follow
closure rules: immutable bindings are copied and mutable bindings are shared.
Constructing the value does not start a fiber.

The type is inferred from the awaited values using their `Awaitable.Rebind`
implementations. `Async` is one such type; `Resource` and custom Awaitable types
work the same way. Awaits inside nested async expressions or closures do not
determine the enclosing expression's type. Incompatible computation contexts
require an explicit annotation or a conversion.

Without an await, provide the Awaitable type through context:

```dovetail
let program: Async<Int32, Never> = async do 42

function makeProgram(): Async<Int32, Never> = async do 42
```

A function parameter can also supply that context. There is no default
Awaitable type for `async do 42` without context.

An async expression has its own early-return and await context. `orReturn`
exits that computation, and loops inside it cannot break or continue an outer
loop. A final expression that itself produces an Awaitable remains a nested
value; use `await` to obtain its result.

Currently, `while` conditions cannot contain `await` or `use`, and an async loop
whose body contains either cannot use `break` or `continue` to exit that iteration.
Synchronous loops inside an async expression support ordinary loop control.

Custom implementations must provide `Awaitable.defer(body: ByName<Self>,
trace: SourceLocation): Self`. This operation stores the by-name value without
evaluating it, then evaluates it and drives its result on each execution.

---

## 12.3 The `await` Operator

`await` is a **prefix** operator — it goes in front of the expression being awaited, not after it. It is only legal inside an async function, async closure, or `async do` expression.

```dovetail
async function greetTwice(): Async<Unit, Never> =
    let first: String = await fetchGreeting()
    let second: String = await fetchGreeting()
    debug(first)
    debug(second)
```

### Awaiting in Control Flow

`await` composes with `if`, `match`, and `while`:

```dovetail
async function pickGreeting(formal: Bool): Async<String, Never> =
    if formal then
        await fetchGreeting()
    else
        await Async.succeed("yo")

async function countUp(n: Int32, sink: (Int32) => Unit): Async<Unit, Never> =
    let mutable i: Int32 = 0
    while i < n do
        let v: Int32 = await Async.succeed(i + 1)
        sink(v)
        i = i + 1
```

### Restrictions

- `await` outside an async function, async closure, or `async do` expression is a compile error.

---

## 12.4 Running Async Code

`main` is a regular synchronous function returning `Unit`. To launch async work, call `Async.run` with the program:

```dovetail
function main(): Unit =
    Async.run(app())

async function app(): Async<Unit, Never> =
    let message: String = await fetchGreeting()
    debug(message)
```

`Async.run`:

- Spins up the runtime and drives the event loop until the program finishes.
- Returns normally when the program succeeds with `Unit`.
- On a typed failure or panic, prints the error to stderr and calls `Process.exit` with an error code.

### Allocation Happens When the Program Runs

`Mutex.make`, `Async.makePromise`, and `Queue.make` return descriptions that allocate fresh state when executed. Running the same constructor program twice creates two objects. Internally, allocation uses `Async.thunk`, even though constructing a class or a waiter itself needs no scheduler instruction.

```dovetail
async function freshPromises(): Async<Unit, Never> =
    let make: Async<Promise<Int32, Never>, Never> = Async.makePromise()
    let first = await make
    let second = await make
    assert !ClassIdentity.equals(first, second)
```

By contrast, constructing one object and putting it in `Async.succeed` captures that existing object for every execution. Preserve this distinction when building reusable programs. Process-wide mutexes use a separate internal constructor for the library's global streams.

### Useful Library Calls

The standard `Async` API in `standard-io` provides the common building blocks:

```dovetail
async function delayed(): Async<Unit, Never> =
    await Async.sleep(Duration.ofMillis(500i64))
    debug("half a second later")
```

---

## 12.5 Parallel Execution

Two async values run sequentially when you `await` them in order. To run work concurrently, **fork** it.

### Fork and Join

`fork` schedules an async value as a child fiber and returns immediately with a handle. `join` waits for that fiber to finish.

```dovetail
async function inParallel(): Async<Int32, Never> =
    let a: Fiber<Int32, Never> = await slowAdd(1, 2).fork()
    let b: Fiber<Int32, Never> = await slowAdd(3, 4).fork()
    let x: Int32 = await a.join()
    let y: Int32 = await b.join()
    await Async.succeed(x + y)
```

Both fibers run concurrently. The two `join` calls wait for whichever fiber needs more time; the second `join` returns immediately if its fiber already finished.

### Structured Concurrency

Every fiber you fork belongs to a **scope**: the innermost enclosing `use` block, or the whole body of the fiber that forked it when there is no `use`. A scope does not finish — a `use` does not release its resource — until every fiber in it is gone. That is what stops a resource from being closed underneath a fiber still reading from it.

What "gone" means depends on how the scope ends and how you forked:

| | scope ends normally | scope ends by failure or interruption |
|---|---|---|
| `fork` | waits for the fiber | interrupts it, then waits |
| `forkBackground` | interrupts it, then waits | interrupts it, then waits |

```dovetail
async function serveAndWait(): Async<Unit, NetError> =
    let listener: TcpListener = use Tcp.bind("127.0.0.1:8080")
    // Structured: the `use` block will not release the listener until this
    // fiber has finished, so it can never read from a closed listener.
    let handler: Fiber<Unit, Never> = await handleOne(listener).fork()
    await handler.join()
```

Use `fork` for work the scope should finish, and `forkBackground` for work that is only meaningful while the scope lives — a poller, a pump, a loop that ends only when the resource it reads from is closed. That last case is the one to watch: a fiber that stops *only* when the resource closes must not be a plain `fork`, or the scope will wait for the fiber while the fiber waits for the scope. The runtime detects that and panics naming both fibers rather than hanging silently.

Note that even a background fiber is waited for once it has been interrupted — the scope waits for it to finish *unwinding*, so its own finalizers always run before the resource is released.

There is deliberately no third option that escapes scopes altogether. A fiber that outlives the resource it was reading from is exactly the hazard scopes exist to prevent, and every use for one turned out to be better served by forking it from a scope that lives long enough — usually the caller's, one level further out.

### Interruption

`Fiber.interrupt` requests cancellation of a fiber. Interruption surfaces inside the fiber as `Cause.Interrupted`. Code that needs to be uncancellable for a critical section can wrap it in `Async.uninterruptible`.

---

## Summary

- `Async<T, E>` is a value describing future work; building one does no work.
- `async function f(): Async<T, E> = ...` declares an async function; the return type is mandatory.
- `await e` is a prefix operator that yields the success value of an async value inside an async body.
- `Async.run(program)` from a synchronous `main` drives the runtime to completion.
- `fork` plus `join` runs work concurrently; structured concurrency means a scope waits for the fibers forked inside it, and `forkBackground` marks the ones it should cancel instead.

### Discarded computations

A bare intermediate expression returning `Async` produces a warning: constructing
a deferred computation does not execute it. Inside a compatible async context,
use `await` to execute it, or return or compose the computation for later use.

```dovetail
async function pause(): Async<Unit, Never> =
    await Async.sleep(Duration.ofSeconds(1i64))
```

`let _ = computation` explicitly acknowledges intentional discard. It **does not
execute** the computation. Bindings and arguments count as using a value; this
warning does not prove that every stored computation is eventually executed.

### Inherited scope context

`ScopeContext<T>` supplies values to an executing scope and its descendant fibers.
Inject one context identity into consumers, then use `context.scope(value)` at the
execution boundary. Children inherit at creation; nested bindings shadow locally,
and joining never merges changes into the parent. See [Scope Context](https://dovetaillang.org/book/resources.md#138-scope-context)
for the API, optional lookup, and lifetime rules.

### Testing time-dependent effects

Use `let clock = use TestClock.install(initial)` and `await clock.advance(duration)`
to drive `Async.sleep`, `timeout`, and time reads without real waiting. Advancement
processes deadlines and settles fibers using that clock; it does not simulate
host I/O or automatically finish sleepers during scope shutdown. See
[Scoped Test Clocks](https://dovetaillang.org/book/resources.md#139-scoped-test-clocks) for a complete example.


---

# Part 13: Resource Management

Source: https://dovetaillang.org/book/resources/


External resources — file handles, network sockets, database connections, locks — need to be released at a precise, known point. Dovetail provides the `use` keyword for that: it binds acquisition and release together so the release always happens when control leaves the scope, whether the scope completes normally, returns early, or fails.

---

## 13.1 The `use` Keyword

`use` is a prefix operator for acquiring a resource inside an async function. It binds the acquired value to a name and guarantees the resource is released when the surrounding scope finishes.

```dovetail
async function copyFile(src: String, dst: String): Async<Unit, IoError> =
    let input = use File.open(src)
    let output = use File.create(dst)
    let bytes: Array<Uint8> = await input.readAll()
    await output.writeAll(bytes)
```

The usual form is `let <name> = use <expression>`, though the binding is optional — `use <expression>` on a line of its own opens the scope and discards the value, which is how `Async.scope()` below is written. The resource expression is evaluated first; the resulting value is bound to the name; everything that follows in the enclosing block runs with the resource alive; when that follow-up finishes, the resource is released.

In `copyFile` above, both files are closed automatically when the function finishes — and they are closed even if `readAll` or `writeAll` fails partway through.

The resources in this part are all asynchronous — external resources almost always have asynchronous acquire and release steps, and `use` is designed around that. `use` itself is not limited to them: the `Usable` trait it desugars through has a synchronous form too, used for things like a secret that must be zeroized after use.

### Fibers forked inside a `use` block

A `use` block is also a **fiber scope**: any fiber forked inside it belongs to the block, and the resource is not released until that fiber is gone. So a fiber cannot end up reading from a socket the block already closed.

```dovetail
async function serveOne(): Async<Unit, NetError> =
    let listener: TcpListener = use Tcp.bind("127.0.0.1:8080")
    // The block will not release the listener until this fiber has finished.
    let worker: Fiber<Unit, Never> = await acceptOne(listener).fork()
    await worker.join()
```

A block that ends normally waits for the fibers forked with `fork`; one that ends by failure interrupts them first. Fibers forked with `forkBackground` are interrupted either way — use that for work that is only meaningful while the resource is open, such as a loop that ends only when the resource closes. See [Part 12](https://dovetaillang.org/book/async.md) for the full comparison.

### Acquisition runs to completion too

Acquiring is **uninterruptible**. A resource becomes real somewhere inside the acquire — the moment the host hands back a socket, say — and the runtime cannot see when; it can only take ownership once the acquire returns. An interrupt landing in between would leave a live resource with nothing left that could close it, so interrupts are held until the acquire finishes and then delivered.

The trade is that an acquisition which parks indefinitely can no longer be cut short. Keep acquisitions bounded and do the waiting inside the block, which stays interruptible. When an acquisition *is* the wait — accepting a connection, taking a lock — it opts back in for that part alone with `.interruptible()`, wrapping the park and never the hand-off, so the fiber can still be cancelled while it waits but the resource still reaches its owner atomically.

### Release runs to completion

Releasing is **uninterruptible**. A finalizer that awaits — a close that flushes, a TLS shutdown that sends `close_notify` — cannot be cut in half by an interrupt arriving part-way through, which would leave the resource neither open nor closed. An interrupt that arrives during a release is deferred and delivered the moment the release finishes, so it is never lost.

The trade is that a finalizer which blocks forever now blocks its fiber forever. Keep release paths bounded: prefer a best-effort close over one that waits indefinitely for a peer.

---

## 13.2 LIFO Release Order

Multiple `use` bindings in the same block release in **last-in, first-out** order, matching the natural nesting:

```dovetail
async function copy(src: String, dst: String): Async<Unit, IoError> =
    let input = use File.open(src)    // released second
    let output = use File.create(dst) // released first
    await pipe(input, output)
```

This matches how you would write the cleanup by hand: outer resources outlive inner ones.

---

## 13.3 Release on Failure

The release step runs whether the body succeeds, fails with a typed error, or produces an async `Cause.Panicked` (for example through `Async.failPanic`). A language-level `panic` or failed `assert` traps and aborts execution; it does not unwind resource scopes. There is no `finally` block to remember and no `try`/`catch` to thread around the work — the keyword itself binds acquisition and release together.

```dovetail
async function process(path: String): Async<Result, ProcessError> =
    let file = use File.open(path)
    await analyze(file)   // even if this fails, the file is closed
```

This is the main reason to reach for `use`: it eliminates the entire class of "I forgot to close that on the error path" bugs.

---

## 13.4 Scopes Without a Resource

A `use` block does two things at once: it opens a scope, and it attaches a resource to it. `Async.scope()` does only the first — it is a resource that acquires nothing, so `use` on it opens a scope and nothing else.

```dovetail
async function handleOne(conn: TcpStream): Async<Unit, NetError> =
    use Async.scope()
    ...
```

Write it bare, with no binding: a scope is never a value, so there would be nothing worth naming. The scope covers **the rest of the enclosing block**, exactly like any other `use`, because it is one. To bound something narrower, give it a block of its own — a loop body, an `if` arm, or a helper function.

What a scope bounds is the two things that attach to one: fibers forked with `fork` / `forkBackground`, and finalizers registered with `attachToScope`. Without a scope of their own, both fall back to the fiber's root scope and live as long as the fiber.

---

## 13.5 Attaching to a Scope You Already Have

`attachToScope` is the other half of `use`. It acquires a resource and hands its release to the innermost open scope, instead of opening a block of its own:

```dovetail
async function serve(certPath: Path, keyPath: Path): Async<Unit, ServerError> =
    use Async.scope()
    let cert = await Certificate.load(certPath).attachToScope()
    let key = await ServerKey.load(keyPath).attachToScope()
    await listen(cert, key)
    // key released, then cert, at the end of the scope
```

Reach for it when the resource's lifetime is a scope that already exists and the acquisition should not swallow the rest of the block as its continuation: a resource acquired in one arm of an `if`, a helper acquiring on its caller's behalf, a loop acquiring a number of resources known only at runtime. When the lifetime *is* the rest of the block, `use` says so more directly.

Note the spelling: always `await`, never `use`. A `use` on it would open a new scope and release at the end of the block, which is exactly what it exists not to do.

### Which scope it attaches to

Whichever is innermost when it runs — the same rule `fork` follows. A scope is never a value, so there is nothing to pass and nothing to pass wrongly. That scope may be an `Async.scope()`, or an ordinary `use` block's, or, if neither is open, the fiber's own root scope, in which case the resource is released when the fiber ends.

A plain `use` block is a perfectly good attach target, and it has to be. Everything releases in **reverse acquisition order**, whichever spelling acquired it:

```dovetail
let socket = use Tcp.connect(host, port)
let file = await File.openInputStream(path).attachToScope()
// file closed first, then socket
```

If the attach could skip the enclosing `use` and land further out, the file would be closed after the socket it was read into — a resource outliving what it was derived from.

### The one thing to watch

An `attachToScope` with no scope of its own lands on the fiber's root scope. That never dangles, and for a server that forks a fiber per request it is exactly right. But a long-running loop that attaches once per turn holds every one of them until the fiber ends. Give each turn a scope and it releases before the next acquires:

```dovetail
while more() do
    await handleOne()          // whose own body opens `use Async.scope()`
```

---

## 13.6 Composing Resources

The `Resource<T, E>` type is itself awaitable. An async function that **returns** a `Resource<T, E>` can use `await` to combine other resources into a single composite resource. Nothing is acquired by the function call itself — what comes back is a description of the combined acquire/release lifecycle, ready to be handed to a `use` site.

```dovetail
async function dbTransaction(): Resource<Transaction, DbError> =
    let conn = await openConnection()
    let txn = await Transaction.begin(conn)
    txn
```

`openConnection` and `Transaction.begin` each return a `Resource<...>`. Inside `dbTransaction`, `await` threads the acquired values through the body, and the function returns a single `Resource<Transaction, DbError>`. The caller never sees the connection — only the transaction it cares about — but the connection is still acquired and, crucially, still released. When the surrounding `use` scope ends, the transaction is closed first and then the connection underneath it, LIFO.

A caller uses that composite resource as if it were any other:

```dovetail
async function runMigration(steps: Array<Migration>): Async<Unit, DbError> =
    let txn = use dbTransaction()
    await applyAll(steps, txn)
```

This is the main reason to write a function that returns a `Resource` rather than `use`-ing one inline: you can package a multi-step setup — connection plus transaction, listener plus accepted socket, lock plus loaded snapshot — into a single named resource and hand it around, exposing only the value the caller actually needs. The LIFO release contract carries across the composition boundary, so callers never have to know how many pieces the resource is made of.

---

## 13.7 Error Conversion at the Use Site

If the resource's failure type differs from the surrounding function's error type, the compiler will convert it automatically — as long as a `From` instance exists between them:

```dovetail
newtype FileError = String
newtype AppError = String

implement From<FileError> for AppError =
    public function from(e: FileError): AppError = AppError("io: " ++ e.value)

async function loadConfig(path: String): Async<Config, AppError> =
    let file = use openConfigFile(path)   // raises FileError, converted via From
    await parseConfig(file)
```

No explicit `.mapError(...)` is needed at the `use` site — the conversion is wired in for you.

---

## 13.8 Scope Context

`standard.io.ScopeContext<T>` lets consumers share a context identity while each
executing scope supplies its own value. Create the identity with
`await ScopeContext<T>.make()` and inject it into the objects that need it.
`await context.get()` returns the nearest binding as `Option<T>`.

`use context.scope(value)` installs a binding for the rest of the block. Its
`ScopeContextScope<T>` result implements `Usable<Unit, Never>`; it is not a
`Resource`, and does not provide resource composition, `attachToScope`, or
`forkAndUse`. Constructing the description does not install a binding.

Nested scopes can shadow a binding. On exit, the previous binding is restored,
including on typed failure, async `Cause.Panicked`, or interruption. Fatal Wasm
traps do not unwind scopes. Forked children inherit the bindings
present when they are created, including background fibers, race branches, and
producer fibers. A child's changes do not affect its parent or siblings, and joining
does not merge them back. Children and finalizers finish before the binding is
removed. A fresh `Async.run()` starts without bindings.

Each execution of `make()` creates a distinct identity, even for the same `T`.
Lookup happens when `get()` executes. Consumers choose how to handle missing values;
there is no implicit default or required-lookup failure.

**Complete example (checked in CI)** — inject one context into a repository and
supply a different value within each execution scope:

<!-- book-example: {"name": "scopecontext", "depends": ["standard-io"]} -->
```dovetail
package scopecontext

import standard.io.Async
import standard.io.ScopeContext

record Repository =
    connections: ScopeContext<String>

module Repository =
    async function connection(self): Async<Option<String>, Never> =
        await self.connections.get()

function main(): Unit =
    let program: Async<Unit, Never> = async do
        let connections = await ScopeContext<String>.make()
        let repository = Repository { connections = connections }
        assert (await repository.connection()).isNone
        use connections.scope("request connection")
        let child = await repository.connection().fork()
        assert (await child.join()).require == "request connection"
    program.run()

test "repository inherits its scoped connection" = main()
```

A context owns its binding, not the bound resource. For a database connection,
acquire the connection with `use` first, then open its context scope. The connection
is released after context users finish. Mutable values remain shared references;
context inheritance does not make a connection safe for concurrent operations.

## 13.9 Scoped Test Clocks

`standard.io.TestClock` freezes time for a scope and its descendant fibers. With
no test clock installed, time reads and sleeps use the real clock. Installation
uses a private `ScopeContext<TestClock>`: nested installations shadow the outer
clock, and independent scopes can use different clocks.

`TestClock.install(initial)` is a reusable `TestClockScope` description implementing
`Usable<TestClock, Never>`. Each `use` creates a fresh clock at `initial` and returns
its controller. Read time through `Instant.now` and the existing date/time
extensions; call `await clock.advance(duration)` to move it forward. `Async.sleep`
and `timeout` use the same virtual timeline, as do consumers of those APIs such
as logging. Direct low-level `standard.wasi.clock` calls still use host time.

**Complete example (checked in CI)**:

<!-- book-example: {"name": "testclock", "depends": ["standard-io"]} -->
```dovetail
package testclock

import standard.io.Async
import standard.io.TestClock
import standard.io.TimeExtension
import standard.time.Instant
import standard.time.Duration

async function delayedTime(): Async<Instant, Never> =
    await Async<Unit, Never>.sleep(Duration.ofSeconds(5i64))
    await Instant.now

function main(): Unit =
    let program: Async<Unit, Never> = async do
        let clock = use TestClock.install(Instant.ofEpochSecond(0i64))
        let child = await delayedTime().fork()
        await clock.advance(Duration.ofSeconds(5i64))
        assert (await child.join()).epochSecond == 5i64
    program.run()

test "sleep completes in virtual time" = main()
```

Advancement first lets runnable fibers using this clock complete or suspend,
so an immediately forked task can register its sleep. It then visits each due
deadline in order, waking equal-deadline sleepers in registration order and letting
relevant work settle before proceeding. A ten-second advance therefore handles
a task that sleeps five seconds and then another five. Wall time and elapsed time
move together, with nanosecond precision; there is no separate wall-clock reset.

`advance(Duration.zero())` settles relevant runnable work without moving time.
Nonpositive virtual sleeps complete immediately; use `Async.yieldNow()` when you
need an explicit scheduling yield. Unrelated runnable fibers do not block clock
advancement, but an endlessly runnable fiber using the clock does. Host I/O is not
simulated: synchronize explicitly with external events. The test runner's
`@timeout` remains a real-time watchdog.

Concurrent advances execute FIFO, computing their relative targets when they
become active. Canceling an advance removes its request without rolling back time
or work already completed. Invalid durations, invalid nanosecond fields, and time
arithmetic outside the representable range produce `Cause.Panicked` without
partially applying the invalid request. Negative advancement is invalid.

Normal scope lifetime rules apply. Background children are interrupted and drained;
structured children must finish. Time is never advanced automatically during
shutdown. Drive sleeping cleanup explicitly, or interrupt outstanding sleepers
before leaving the scope. A stalled runtime identifies virtual waiters in its
diagnostic. Bindings remain installed through cleanup, and clock handles become
invalid after installation closes. Using a handle in a different `Async.run()`
also produces an async defect; each runtime starts without clock bindings.

## Summary

- `use` acquires a resource inside an async function and guarantees release when the enclosing scope exits — on success, typed failure, or async `Cause.Panicked`.
- A `use` block is a fiber scope: fibers forked inside it finish (or are cancelled) before the resource is released.
- Acquisition and release are both uninterruptible by default: an interrupt arriving during either is deferred until it completes, so a resource is never stranded half-owned or left half-closed. An acquisition that *is* a wait opts its park back in with `.interruptible()`; a release never can.
- Syntax is `let x = use expr`, or bare `use expr` when the value is not wanted; multiple `use` bindings in a block release in LIFO order.
- `use Async.scope()` opens a scope that acquires nothing, for bounding forked fibers and attached resources.
- `await r.attachToScope()` acquires `r` and releases it when the innermost open scope closes, rather than opening a scope of its own. Everything releases in reverse acquisition order, whichever spelling acquired it.
- An async function returning `Resource<T, E>` can use `await` to compose other resources into a single composite resource.
- `From` instances are used automatically to convert a resource's error type into the surrounding function's error type.

For helpers that accept an unknown resource type through a `Usable` bound, see
[Generic Resource Helpers](https://dovetaillang.org/book/advanced-generics.md#generic-resource-helpers).

### Discarded resources

An intermediate expression returning `Resource` produces a warning. A resource
value describes deferred acquisition and release; discarding it does not acquire
the resource. Use `let value = use resource` in a compatible context, or return
or compose the resource for later acquisition. `use resource` without a binding
also counts as acquisition and does not produce this warning.

Write `let _ = resource` only when discarding the description is intentional.
This acknowledges discard; it **does not acquire** the resource or run its work.


---

# Part 14: Streams

Source: https://dovetaillang.org/book/streams/


An `Async<T, E>` describes one asynchronous result. A `Stream<T, E>` describes a sequence of values of type `T`, which can end normally or fail with an error of type `E`. The sequence can be finite, or it can keep producing values until its consumer stops.

Streams belong to the `standard-io-stream` project. Add it to your project's `depends` list and import `standard.io.stream.Stream`. The examples below also use `standard.io.Async`; examples involving time use `standard.time.Duration`.

---

## 14.1 Descriptions and Consumption

Like an async computation or a resource, a stream is a reusable description. Constructing a stream does not start its source. A terminal operation such as `runCollect` produces an `Async` value; running that value starts consumption.

```dovetail
import standard.io.Async
import standard.io.stream.Stream

async function streamExample(): Async<Unit, Never> =
    let numbers = Stream<Int32, Never>.fromList([1, 2, 3, 4])
        .filter((number: Int32) => number % 2 == 0)
        .map((number: Int32) => number * 10)

    assert (await numbers.runCollect()) == [20, 40]
    assert (await numbers.runCollect()) == [20, 40]

function main(): Unit = streamExample().run()
```

Each consumption gets fresh execution state. Reusing a description does not rewind an external queue, restore a file position, or snapshot an array. Those objects keep their own state.

Source constructors use by-name arguments where evaluating the argument belongs to execution. For example, `Stream.succeed(nextValue())` evaluates `nextValue()` when that source is reached during consumption. You do not need to pass a thunk. The same applies to the initial state of an unfold and the second stream in `concat`.

Both type parameters are covariant: a `Stream<Uint8, Never>` can be used as a `Stream<Any, Never>`. This widening preserves the original values and their types.

---

## 14.2 Creating a Source

Use a constructor that matches where the values come from:

| Constructor | Source behavior |
| --- | --- |
| `Stream<T, E>.empty` | Ends without emitting a value; this is a property. |
| `succeed(value)` | Emits one value. |
| `fromList(values)` | Emits the elements of a list in order. |
| `fromChunk(chunk)` | Emits a `ReadonlySlice<T>`. |
| `fromAsync(effect)` | Runs an `Async<T, E>` once and emits its result. |
| `fromQueue(queue)` | Takes values from a standard-io `Queue<T>`, waiting when it is empty. |
| `fail(error)` | Fails with a typed error. |

A queue source has no end-of-stream marker. It continues taking values until it fails, is cancelled, or a downstream operation such as `take` stops demand. `fromQueue` currently requires `T: Default`, as the queue API does. Every consumption uses the queue supplied to it, so consuming the same description twice can receive different values.

### Unfolding state

An unfold constructs the next item and the next state together. Returning `None` ends a pure unfold.

```dovetail
async function unfoldExample(): Async<Unit, Never> =
    let numbers = Stream<Int32, Never>.unfold(0, (state: Int32) =>
        if state < 4 then Some((state, state + 1))
        else None
    )
    assert (await numbers.runCollect()) == [0, 1, 2, 3]
```

The step for `unfold<S>` has type `S => Option<(T, S)>`. Its chunk counterpart, `unfoldChunk<S>`, returns `Option<(ReadonlySlice<T>, S)>`.

For asynchronous unfolds, normal completion travels through the optional error channel:

```dovetail
async function asyncUnfoldExample(): Async<Unit, String> =
    let numbers = Stream<Int32, String>.unfoldAsync(0, async (state: Int32) =>
        if state < 3 then (state, state + 1)
        else await Async<(Int32, Int32), Option<String>>.fail(None)
    )
    assert (await numbers.runCollect()) == [0, 1, 2]
```

The step for `unfoldAsync<S>` returns `Async<(T, S), Option<E>>`. Success emits an item and installs the next state, failure with `None` ends the stream normally, and failure with `Some(error)` fails the stream with `error`. `unfoldChunkAsync<S>` follows the same convention with a `ReadonlySlice<T>` in place of the item.

---

## 14.3 Chunks and Transformations

Streams transport values in chunks. A chunk is a `ReadonlySlice<T>`: a bounded view over array storage. Read-only access does not freeze the array. Writes through another alias remain visible, so a source must not overwrite a chunk while its consumer still needs those values. Use `toArray().readonly` when an independent copy is needed.

`map` and `filter` work with individual values while processing their input chunks. `mapChunks` and `mapChunksAsync` give the callback a whole slice. A chunk callback may return a different number of values, including none. Empty chunks are skipped.

```dovetail
async function chunkExample(): Async<Unit, Never> =
    let source = Stream<Int32, Never>.fromChunk([|1, 2, 3, 4|].readonly)
    let selected = source.mapChunks((chunk: ReadonlySlice<Int32>) => chunk.drop(1))
    assert (await selected.runCollect()) == [2, 3, 4]
```

### Effectful operations work one item at a time

`mapAsync` and `filterAsync` break chunks into single items before applying their effect. This makes downstream demand control how many item effects run.

```dovetail
async function itemEffectsExample(): Async<Unit, Never> =
    let mutable calls = 0
    let values = Stream<Int32, Never>.fromChunk([|1, 2, 3|].readonly)
        .mapAsync(async (value: Int32) =>
            calls = calls + 1
            value * 10
        )
        .take(1)

    assert (await values.runCollect()) == [10]
    assert calls == 1
```

Likewise, `filterAsync(predicate).take(1)` runs the predicate only until the first accepted item. A whole-chunk operation behaves differently: `mapChunksAsync(f).take(1)` runs `f` for the entire first input chunk it reaches. Pure `map` also processes a whole input chunk before returning it downstream.

`take(count)` limits the number of emitted items; `drop(count)` skips items, crossing chunk boundaries when necessary. `rechunk(size)` combines or splits input chunks into chunks of the requested positive size, with a possibly smaller final chunk. Rechunking preserves item order but copies into new backing arrays.

---

## 14.4 Concatenation and Flat Mapping

`concat` consumes its first stream completely before evaluating and consuming the second. If the first stream fails, the second is not started.

`flatMap` replaces each item with another stream. It consumes that inner stream completely before moving to the next outer item. This is sequential composition.

```dovetail
async function compositionExample(): Async<Unit, Never> =
    let expanded = Stream<Int32, Never>.fromList([1, 2])
        .flatMap((value: Int32) =>
            Stream<Int32, Never>.fromList([value, value * 10])
        )
        .concat(Stream<Int32, Never>.succeed(99))

    assert (await expanded.runCollect()) == [1, 10, 2, 20, 99]
```

`repeat()` restarts a stream after normal completion. It reuses the description with fresh execution state each time. An error stops repetition. Repeating an empty stream produces no items; use a source that can make progress when downstream is waiting for a value.

---

## 14.5 Repeating Effects and Time

Repeating an effect is useful for polling or reading from a source whose next value is obtained asynchronously.

| Constructor | Effect type and completion |
| --- | --- |
| `repeatAsync(effect)` | Repeats `Async<T, E>` until failure or cancellation. |
| `repeatAsyncChunk(effect)` | Repeats `Async<ReadonlySlice<T>, E>`. |
| `repeatAsyncOption(effect)` | Repeats `Async<T, Option<E>>`; `None` ends normally. |
| `repeatAsyncChunkOption(effect)` | The same completion convention for chunk effects. |
| `repeatAsyncWithInterval(effect, interval)` | Runs immediately, then waits the duration before each subsequent execution. |
| `Stream<Unit, E>.tick(interval)` | Waits before every tick and emits `Unit`. |

These sources produce values on demand. They do not accumulate missed ticks or run a polling effect independently of consumption. An interval is a delay between executions, not a fixed wall-clock schedule.

```dovetail
import standard.time.Duration

async function ticksExample(): Async<Unit, Never> =
    let ticks = Stream<Unit, Never>.tick(Duration.ofMillis(1i64))
    assert (await ticks.take(3).runCollect()).length == 3
```

An infinite stream needs a stopping condition when consumed by a terminal operation that waits for completion. `take` provides an item limit; ordinary async cancellation and timeout operations apply to the resulting `Async` as well.

---

## 14.6 Errors and Resource Lifetimes

Normal completion and typed failure are different outcomes. `mapError` transforms a typed error. `catchAll` replaces a failed stream with a recovery stream; values already emitted remain before the recovery values.

```dovetail
async function recoveryExample(): Async<Unit, Never> =
    let source = Stream<Int32, String>.succeed(1)
        .concat(Stream<Int32, String>.fail("unavailable"))
        .catchAll((_: String) => Stream<Int32, Never>.succeed(9))

    assert (await source.runCollect()) == [1, 9]
```

`catchAll` handles the typed error channel, not defects or interruption. Failures and cancellation propagate through the consuming `Async`, which still runs cleanup.

### Acquiring resources inside a stream

`fromResource(resource)` acquires a `Resource<T, E>` and emits its value. Its lifetime covers the downstream stream work in that scope. A common pattern is to acquire a handle and `flatMap` into the stream that reads it. `bracket(acquire, release)` is the equivalent constructor when you have acquisition and release effects directly.

```dovetail
async function lifetimeExample(): Async<Unit, Never> =
    let mutable releases = 0
    let source = Stream<Int32, Never>.bracket(
        Async.succeed(10),
        async (_: Int32) =>
            releases = releases + 1
    ).flatMap((value: Int32) =>
        Stream<Int32, Never>.fromList([value, value + 1])
    )

    assert (await source.take(1).runCollect()) == [10]
    assert releases == 1
```

Acquisition happens when consumption reaches the resource. Release runs when its stream scope finishes, including on early termination, failure, and cancellation. An inner stream's resources close before sequential `flatMap` advances to the next outer item. Fibers forked while interpreting that stream belong to its scope, following the structured-concurrency rules from [Async Programming](https://dovetaillang.org/book/async.md) and [Resource Management](https://dovetaillang.org/book/resources.md).

`ensuring(finalizer)` attaches a finalizer to a stream without emitting a resource value. The finalizer is also evaluated as part of execution.

---

## 14.7 Merging Concurrent Sources

`merge(other)` consumes two sources concurrently; `Stream<T, E>.mergeAll(streams)` does the same for a list of sources. Each source preserves its own order, while order between sources depends on which one produces the next chunk.

```dovetail
async function mergeExample(): Async<Unit, Never> =
    let left = Stream<Int32, Never>.fromList([1, 2])
    let right = Stream<Int32, Never>.fromList([3, 4])
    let total = await left.merge(right).fold(0, (sum: Int32, value: Int32) => sum + value)
    assert total == 10
```

Merge completes normally once all its sources finish. A source failure is delivered through the same handoff as chunks, so it does not jump ahead of chunks already handed off to the consumer. When the merge fails or downstream stops early, the remaining producers are interrupted and their resources are released.

The handoff applies backpressure: a producer waits for the consumer to accept its chunk. Acceptance does not mean downstream has finished processing every item in it. The producer may continue, finish, and close its resources while the consumer is processing that chunk. Emit values whose use does not depend on the producer remaining open. In particular, do not treat a resource handle passed through a merge as if it retained the sequential `flatMap` lifetime guarantee.

---

## 14.8 Running and Folding

Terminal operations turn the stream description into an async computation:

| Operation | Result |
| --- | --- |
| `runCollect()` | `Async<List<T>, E>`, retaining all emitted items in order. |
| `fold(initial, combine)` | `Async<S, E>`, accumulating one state with a pure `(S, T) => S` function. |
| `foreach(effect)` | `Async<Unit, E>`, awaiting an effect for each item in order. |
| `foreachChunk(effect)` | `Async<Unit, E>`, awaiting an effect for each chunk. |
| `drain()` | `Async<Unit, E>`, consuming values without retaining them. |

The initial state passed to `fold` is by-name and is evaluated afresh for each execution. Folding can keep memory bounded when the accumulator itself has bounded size. `runCollect` needs memory for the entire result and waits for the stream to end, so reserve it for finite streams of an appropriate size.

Use `await` to consume a stream inside a larger async program, or `.run()` at the application boundary, just as in [Part 12](https://dovetaillang.org/book/async.md).

---

## 14.9 Byte Transports

Files and TCP connections expose `AsyncInputStream<E>` and `AsyncOutputStream<E>` handles. Adapt a borrowed input with `Stream<Uint8, E>.fromInputStream(input, chunkSize)`. The chunk size is a required, positive `Int64`; `65536i64` requests up to 64 KiB per read. Short reads produce chunks normally, and an empty read ends the stream.

For output, `Stream.writeToOutputStream(output)` accepts an `AsyncOutputStream<E>` destination. Its `where T: Uint8, E: IoError` bounds make it available on byte streams. It awaits each chunk write before asking for another chunk. Both adapters use the handles' natural I/O error type.

Neither adapter closes a handle, and `writeToOutputStream` does not flush. The code that owns the resource decides when those operations happen. An empty source performs no writes.

### Copying a file

```dovetail
import standard.io.Async
import standard.io.fs.File
import standard.io.fs.FileStreamError
import standard.io.fs.Path
import standard.io.stream.Stream
import standard.wasi.fs.FileSystemError

async function copyFile(source: Path, destination: Path): Async<Unit, FileStreamError> =
    let input = use File.openInputStream(source)
    let output = use File.openOutputStream(destination)
    await Stream<Uint8, FileSystemError>.fromInputStream(input, 65536i64).writeToOutputStream(output).mapError(FileStreamError.from)
    await output.close().mapError(FileStreamError.from)
```

The resource errors are `FileStreamError`, while reads and writes report `FileSystemError`. The filesystem library provides `From<FileSystemError>` for `FileStreamError`, used explicitly with `mapError` to convert transport errors.

The explicit `close()` observes late output failures that may arrive after the host accepts the bytes. Resource cleanup still owns releasing the handles on every exit path.

### Owning a source through composition

A stream that should open a fresh file for every consumption can compose the resource constructor:

```dovetail
function fileBytes(path: Path): Stream<Uint8, FileStreamError> =
    Stream.fromResource(File.openInputStream(path))
        .flatMap(input =>
            Stream<Uint8, FileSystemError>.fromInputStream(input, 65536i64)
                .mapError(FileStreamError.from)
        )
```

This preserves the file's lifetime through sequential downstream processing, and closes it on completion, failure, cancellation, or early termination. Reusing a borrowed handle instead continues from that handle's current position; stopping partway through a chunk does not put its unread items back into the transport.

TCP uses the same pattern, except a connection resource owns both directions together:

```dovetail
import standard.io.net.Tcp
import standard.io.net.NetError
import standard.wasi.net.NetworkError

async function echoOnce(address: String): Async<Unit, NetError> =
    let listener = use Tcp.bind(address)
    let connection = use listener.accept()
    await Stream<Uint8, NetworkError>.fromInputStream(connection.input, 65536i64)
        .writeToOutputStream(connection.output).mapError(NetError.from)
    await connection.output.close().mapError(NetError.from)
```

The connection stays alive while its input and output are used together. The existing conversion from `NetworkError` to `NetError` is used with `mapError` for transport errors.

### Readonly output windows

`AsyncOutputStream.write` accepts `ReadonlySlice<Uint8>`. Use `array.readonly` or `slice.readonly` for existing buffers. A stream chunk, including an interior window, passes directly to the output adapter without an intermediate array copy. WASI still copies the selected bytes into host memory, and TLS builds the owned record buffer required for encryption.


---

# Part 15: Testing

Source: https://dovetaillang.org/book/testing/


Testing is a first-class feature in Dovetail. Tests are written directly in your source files alongside your code, making it easy to keep tests close to the implementation they verify.

---

## 15.1 Unit Tests

### Basic Test Syntax

Tests are declared using the `test` keyword followed by a string name and a body:

```dovetail
function add(a: Int32, b: Int32): Int32 = a + b

test "addition works" =
    assert add(1, 2) == 3
```

The test name is a descriptive string that appears in test output. The body contains assertions that verify expected behavior.

### The assert Expression

The `assert` expression checks that a condition is true. If the condition is false, the test fails with a panic:

```dovetail
test "basic assertions" =
    assert 1 + 1 == 2
    assert "hello".length == 5
    assert true
```

Multiple assertions can appear in a single test. The test passes only if all assertions succeed:

```dovetail
test "multiple assertions" =
    let result = calculateTotal(100.0, 5)
    assert result > 0.0
    assert result == 540.0  // 100 * 5 * 1.08 (with tax)
```

### Testing with Let Bindings

Tests can use `let` bindings to set up test data:

```dovetail
record User =
    name: String
    age: Int32

test "user creation" =
    let user = User { name = "Alice"; age = 30 }
    assert user.name == "Alice"
    assert user.age == 30
```

### Testing Functions

Tests typically call functions and verify their output:

```dovetail
function fibonacci(n: Int32): Int32 =
    if n <= 1 then n
    else fibonacci(n - 1) + fibonacci(n - 2)

test "fibonacci base cases" =
    assert fibonacci(0) == 0
    assert fibonacci(1) == 1

test "fibonacci sequence" =
    assert fibonacci(5) == 5
    assert fibonacci(10) == 55
```

---

## 15.2 Test Organization

Dovetail supports two testing models: **unit tests** in source files and **integration tests** in a separate `test/` directory.

### Unit Tests in Source Files

Unit tests are placed in the same file as the code they test. This keeps tests close to implementation and allows tests to access private members:

```dovetail
package myapp.math

function square(x: Int32): Int32 = x * x

function cube(x: Int32): Int32 = x * x * x

// Tests for this module - can access private functions
test "square of positive" =
    assert square(3) == 9

test "square of negative" =
    assert square(-4) == 16

test "cube of positive" =
    assert cube(2) == 8
```

Unit tests have direct access to all functions in the file, including private ones.

### Integration Tests in test/ Directory

Integration tests live in a `test/` directory at the project root. These tests use `package test` and import symbols from the main packages:

```
project/
├── src/
│   └── math.dove       # Contains unit tests inline
└── test/
    ├── mathTest.dove   # Integration tests (package test)
    └── utils/
        └── helpersTest.dove  # package test.utils
```

Integration test files use `package test` (or `package test.<subpath>` for subdirectories) and import from the main package:

```dovetail
// test/mathTest.dove
package test

import myapp.math.square
import myapp.math.cube

test "integration square" =
    assert square(5) == 25

test "integration cube" =
    assert cube(3) == 27
```

Integration tests:
- Use `package test` as their package declaration (the `test` package prefix is reserved and cannot be used in `src/`)
- Must import functions and types from the main packages — can access **public and internal** (default visibility) symbols, but not private members
- Are discovered automatically when running `dovetail test`

### When to Use Each Model

**Use unit tests** (in `src/`) when:
- Testing internal implementation details
- Testing private helper functions
- Tests need access to module internals

**Use integration tests** (in `test/`) when:
- Testing the public API of your package
- Verifying behavior from an external perspective
- Tests should only use public and internal interfaces

### Testing Enums and Pattern Matching

Tests can verify enum behavior and pattern matching:

```dovetail
enum Result<T, E> =
    Ok(T)
    Error(E)

function divide(a: Int32, b: Int32): Result<Int32, String> =
    if b == 0 then
        Error("Division by zero")
    else
        Ok(a / b)

test "successful division" =
    match divide(10, 2) with
        case Ok(result) => assert result == 5
        case Error(_) => assert false

test "division by zero" =
    match divide(10, 0) with
        case Ok(_) => assert false
        case Error(msg) => assert msg == "Division by zero"
```

### Testing Classes

Tests work with classes just like any other type:

```dovetail
class Counter() =
    let mutable count: Int32 = 0

    public function increment(self): Unit =
        self.count = self.count + 1

    public function getCount(self): Int32 = self.count

test "counter increments" =
    let counter = Counter()
    assert counter.getCount() == 0
    counter.increment()
    assert counter.getCount() == 1
    counter.increment()
    counter.increment()
    assert counter.getCount() == 3
```

---

## 15.3 Test Attributes

Test attributes modify test behavior. They are placed before the `test` keyword using `@` syntax.

### @skip - Skipping Tests

Use `@skip` to temporarily disable a test:

```dovetail
@skip
test "work in progress" =
    assert newFeature() == expected
```

Provide a reason for skipping:

```dovetail
@skip("Waiting for API v2")
test "new api test" =
    assert callNewApi() == expected
```

Skipped tests appear in the output but don't run:

```
    ○ new api test (Waiting for API v2)
```

### @panics - Expecting Panics

Use `@panics` when a test should cause a panic:

```dovetail
function divideUnsafe(a: Int32, b: Int32): Int32 = a / b

@panics
test "division by zero panics" =
    let result = divideUnsafe(10, 0)
    assert result == 0  // Never reached
```

A test marked with `@panics`:
- **Passes** if the code panics
- **Fails** if the code completes without panicking

You can optionally specify an expected panic message substring:

```dovetail
@panics("out of bounds")
test "array access panics with message" =
    let arr = [|1, 2, 3|]
    let x = arr[100]  // Should panic with "out of bounds"
```

### @timeout - Test Timeouts

Use `@timeout` to limit how long a test can run (in milliseconds):

```dovetail
@timeout(1000)
test "completes quickly" =
    let result = fastOperation()
    assert result == expected
```

If the test takes longer than the timeout, it fails with a timeout diagnostic.

### Combining Attributes

Multiple attributes can be combined:

```dovetail
@timeout(5000)
@skip("Flaky on CI")
test "network test" =
    let response = fetchRemoteData()
    assert response.status == 200
```

---

## 15.4 Running Tests

### The dovetail test Command

Run all tests in your project:

```bash
dovetail test
```

Individual results are shown by default, grouped by project and source file.
There is no `test --verbose` flag. The summary reports passed, failed, and skipped
tests. A filter matching no tests exits successfully, so check the count in CI.

### Filtering Tests

Run only tests whose fully qualified test name (FQTN) contains a substring:

```bash
dovetail test --filter "addition"
```

The `--filter` (or `-f`) flag matches against the full FQTN (`<package_path> <test_name>`). Multiple `--filter` flags are OR'd — a test runs if it matches any filter:

```bash
dovetail test --filter "addition" --filter "subtraction"
```

### Filtering by File

Run only tests defined in a specific source file:

```bash
dovetail test --file src/math.dove
```

### Testing Specific Projects

In a multi-project workspace, run tests for a specific project using a positional argument:

```bash
dovetail test myapp
```

Filters can be combined with the project argument:

```bash
dovetail test myapp --filter "math" --file src/math.dove
```

### Exit Codes

The `dovetail test` command returns:
- **0** if all tests pass (or are skipped)
- **1** if any test fails
- **2** if there is a compilation error

This makes it easy to use in CI/CD pipelines:

```bash
dovetail test
```

### Test Output Format

Results use `✓` for passed tests, `✗` for failures, and `○` for skipped tests.
Failures include diagnostics and a final failure summary.

---

## 15.5 Testing Best Practices

### Write Descriptive Test Names

Good test names describe the expected behavior:

```dovetail
// Good
test "returns None when user not found" =
    assert findUser(999).isNone

// Less clear
test "test1" =
    assert findUser(999).isNone
```

### One Concept Per Test

Each test should verify one specific behavior:

```dovetail
// Good: separate tests for separate behaviors
test "empty list has zero length" =
    assert [].length == 0

test "single element list has length one" =
    assert [42].length == 1

// Avoid: multiple unrelated assertions
test "list operations" =
    assert [].length == 0
    assert [1].length == 1
    assert [1, 2].contains(1)
    assert [1, 2].sum() == 3
```

### Test Edge Cases

Include tests for boundary conditions and error cases:

```dovetail
function safeDivide(a: Int32, b: Int32): Option<Int32> =
    if b == 0 then None else Some(a / b)

test "divide positive numbers" =
    assert safeDivide(10, 2).require == 5

test "divide by zero returns None" =
    assert safeDivide(10, 0).isNone

test "divide with negative numbers" =
    assert safeDivide(-10, 2).require == -5

test "divide zero by nonzero" =
    assert safeDivide(0, 5).require == 0
```

### Use Helper Functions

Extract common setup into helper functions:

```dovetail
function createTestUser(name: String): User =
    User { name = name; age = 25; email = "$name@test.com" }

test "user greeting" =
    let user = createTestUser("Alice")
    assert user.greet() == "Hello, Alice!"

test "user email" =
    let user = createTestUser("Bob")
    assert user.email == "Bob@test.com"
```

### Keep Tests Fast

Tests should run quickly. Use `@timeout` to catch slow tests:

```dovetail
@timeout(100)
test "lookup is fast" =
    let result = cache.lookup("key")
    assert result == Some("value")
```

---

## Summary

- Tests are declared with `test "name" = body` and always return `Unit`
- Use `assert` to verify conditions
- Use `@skip` to disable tests temporarily
- Use `@panics` for tests that should panic
- Use `@timeout` to limit test duration
- Run tests with `dovetail test`
- Use `--filter` to run specific tests
- Use `--file` to run tests from a specific source file
- Write descriptive names and test one concept per test


---

# Part 16: Macros

Source: https://dovetaillang.org/book/macros/


Dovetail has one form of metaprogramming: **derive macros**. A derive macro looks at a record, enum, or newtype declaration and generates an `implement` block for it — typically a trait implementation that would otherwise be tedious or error-prone to write by hand. Equality, hashing, JSON encoding and decoding, and similar structural operations are good fits.

This chapter covers the `@derive` keyword on the user side, the built-in derives that ship with the compiler and the standard library, and how to write your own derive macro in Rhai.

> **See also:** [Part 24: Prefixed String Literals](https://dovetaillang.org/book/prefixed-literals.md) is the same bargain applied to syntax rather than declarations — the compiler lexes `sql"..."` and defines what `$` may do, and a library decides what the literal means by marking a name `@stringLiteral`.

---

## 16.1 Overview

The macros described here run at **compile time**. They generate Dovetail source code, the compiler type-checks the generated code along with everything else, and the rest of the pipeline proceeds as if you had written the implementation by hand. There is no runtime cost — and no way for a macro to do anything at runtime, either.

Dovetail deliberately keeps the surface small:

- The only form of macro available today is the **derive macro**, applied to a record, enum, or newtype.
- There are no expression-level macros, no token tricks, no syntax extensions. Macros do not introduce new keywords or operators.
- A derive macro's only job is to emit a single `implement` block.

This keeps generated code readable, predictable, and easy to reason about. If you can't tell what code a macro would produce just by knowing the type and the trait, the macro is probably trying to do too much.

---

## 16.2 The `@derive` Attribute

The `@derive` attribute goes directly above a record, enum, or newtype declaration. It names a single macro to apply.

```dovetail
@derive(Equatable)
record Point =
    x: Int32
    y: Int32
```

This generates an `implement Equatable for Point` block — a structural equality check that compares each field. The original declaration is unchanged; the derive sits beside it.

### Multiple Derives

To apply more than one derive, stack the attributes. Each `@derive` names exactly one macro:

```dovetail
@derive(Equatable)
@derive(JsonEncoder)
@derive(JsonDecoder)
record User =
    name: String
    age: Int32
```

Order does not matter — each derive sees the original declaration, not the output of the previous one. The compiler runs them all and adds each generated `implement` block to the package.

### Enums and Newtypes

Derives work the same way on enums and newtypes:

```dovetail
@derive(Equatable)
enum Shape =
    Circle(Float64)
    Rect { width: Float64, height: Float64 }
    Empty

@derive(Equatable)
newtype UserId = Int64
```

A single derive macro typically handles all three kinds; the macro inspects what it was given and emits code accordingly.

### Derives and Private Types

Generated implementations obey the same access rules as handwritten ones. `@derive(Equatable)` can compare a private record's fields or match a private enum's variants, since those operations remain public. A decoder that directly constructs either type is rejected outside its associated module.

Private newtypes also hide `.value` and unwrapping patterns. A derive that reads the wrapped value directly, including the standard `Equatable` derive, therefore cannot be used on a private newtype. Use an implementation that delegates to the associated module, or a derive that generates those module calls. For decoding, a useful approach is to decode a public snapshot and pass it to a module function that validates and constructs the private value.

### Generic Types

When the target type has type parameters, the macro adds the corresponding trait bounds for you. Deriving `Equatable` for a generic record:

```dovetail
@derive(Equatable)
record Box<T> =
    value: T
```

produces an `implement` block that requires `T: Equatable` — so `Box<Int32>` is equatable, but `Box<SomeNonEquatableType>` is rejected at the call site with a clear error.

### Fully Qualified Macro Names

If two macros share a name, or you want to be explicit, use a dotted path:

```dovetail
@derive(standard.json.JsonEncoder)
record Point =
    x: Int32
    y: Int32
```

The short form (`@derive(JsonEncoder)`) works whenever a macro of that name is reachable; the qualified form is unambiguous.

---

## 16.3 Built-in Derives

The compiler and standard library ship a small set of derives. These are the most common ones and are the only "magic" — everything else is just a derive that you (or some library) wrote.

| Derive | Package | Trait it implements |
|---|---|---|
| `Equatable` | `standard.prelude` | Structural equality (`equals`) |
| `JsonEncoder` | `standard.json` | Convert the type to JSON (`toJson`) |
| `JsonDecoder` | `standard.json` | Parse the type from JSON (`fromJson`) |
| `YamlDecoder` | `standard.yaml` | Decode the type from YAML (`fromYaml`) |

`Equatable` is available everywhere because the prelude is always in scope. `JsonEncoder` and `JsonDecoder` require project `standard-json`; `YamlDecoder` requires project `standard-yaml`.

YAML decoding rejects unknown fields and treats missing optional fields as `None`.
Import `Yaml` and `YamlError` with `YamlDecoder`. See [YAML](https://dovetaillang.org/book/stdlib.md#2211-yaml)
for the supported input subset, enum representation, and error handling.

These derives follow the structural rule: for a record, each field is encoded/compared in turn; for an enum, each variant is handled; for a newtype, the single inner value carries through.

```dovetail
@derive(JsonEncoder)
record Point =
    x: Int32
    y: Int32

function main(): Unit =
    let p = Point { x = 1, y = 2 }
    debug(p.toJson().stringify())   // {"x":1,"y":2}
```

---

## 16.4 Writing Custom Derives (Rhai)

A derive macro is a [Rhai](https://rhai.rs) script that returns Dovetail source code as a string. The compiler runs the script once per type that names the derive, parses the returned string back into a declaration, and adds it to the package.

### Registering a Macro

Macros live in your project alongside the source. A `[[project.macro]]` entry in `Dovetail.toml` tells the compiler the name, the trait it implements, and where to find the script:

```toml
[[project.macro]]
name = "Hashable"
package = "my.app"
kind = "derive"
trait = "my.app.Hashable"
script = "macros/Hashable.rhai"
```

Once registered, any package that depends on `my.app` can write `@derive(Hashable)` on a record or enum.

### The `input` Variable

A derive script receives a constant named `input` describing the type it is being applied to:

```rhai
input = #{
    kind: "record",          // or "enum" or "newtype"
    name: "Point",
    type_params: [],
    fields: [
        #{ name: "x", ty: "Int32" },
        #{ name: "y", ty: "Int32" },
    ],
    // For enums:
    // variants: [ #{ name: "...", kind: "none" | "tuple" | "record", types: [...], fields: [...] } ]
    // For newtypes:
    // inner: "Int32"
}
```

The script reads `input` and returns a string. That string must be a valid Dovetail `implement` block for the trait the macro is registered to.

### A Small Example: a `Tag` Derive

Suppose we want a derive that implements a tiny `Tag` trait, returning the type's own name as a string:

```dovetail
public trait Tag =
    function tag(self: Self): String
```

The Rhai script is short:

```rhai
fn join(items, sep) {
    if items.is_empty() { return ""; }
    let s = items[0];
    for i in 1..items.len() { s += sep + items[i]; }
    s
}

let type_args = if input.type_params.is_empty() {
    ""
} else {
    "<" + join(input.type_params, ", ") + ">"
};

`implement Tag for ${input.name}${type_args} =
    public function tag(self: ${input.name}${type_args}): String = "${input.name}"
`
```

The script's last expression is the return value — a backtick template that interpolates `input.name` into the generated Dovetail source. Using it is then just:

```dovetail
@derive(Tag)
record Cat =
    age: Int32

function main(): Unit =
    let c = Cat { age = 3 }
    debug(c.tag())   // Cat
```

### Generating from Fields and Variants

A more realistic derive iterates over `input.fields` (for records) or `input.variants` (for enums). The structural-equality derive does both: for records it joins `self.f == other.f` for every field with `&&`; for enums it builds a `match (self, other) with ...` whose arms unpack each variant on both sides and compare component-by-component.

The pattern is always the same: read `input`, build up a Dovetail source string, return it.

### Conventions

A few practical points keep custom derives well-behaved:

- **Generate one `implement` block.** Derive macros are not for adding arbitrary declarations to the package.
- **Add trait bounds for every type parameter.** If your derive emits `T: MyTrait` bounds in the generated `where` clause, the type system rejects misuse at the call site with a useful message.
- **Keep the script readable.** A derive is a description of code a human could have written. If the script is hard to follow, the generated code will be too.
- **Test against records, enums (with all three payload shapes: none, tuple, record), and newtypes.** A derive that only handles one of these is a derive that quietly fails to apply elsewhere.

---

## Summary

- `@derive(Name)` above a record, enum, or newtype generates an `implement` block at compile time.
- Stack multiple `@derive` attributes to apply more than one; order does not matter.
- Generic targets get the right trait bounds added automatically.
- Built-in derives: `Equatable`, `JsonEncoder`, `JsonDecoder`.
- Custom derives are Rhai scripts that read an `input` description and return Dovetail source as a string; register them in `Dovetail.toml`.


---

# Part 17: Components

Source: https://dovetaillang.org/book/components/


Dovetail programs can use libraries written in **other languages** — C, Rust, Go — as long as they are packaged as **WASM components** (the WASI component model). A component is a self-contained `.wasm` file that describes its own interface in **WIT** (WebAssembly Interface Types). Dovetail treats that interface as the boundary: the compiler reads it, generates a low-level Dovetail bindings package for it, and links the component into your program at build time.

There is no foreign function interface, no header files, and no glue code to write. The final artifact is still a single portable component whose only requirements are standard WASI — use the matching Dovetail runtime to provide its required host interfaces.

This part covers *consuming* components. **SQLite** is a full database compiled to WASM and shipped as an artifact of the `standard-sqlite` library. Its Git revision pins both the Dovetail wrapper and the component binary.

---

## 17.1 Declaring a Component Dependency

Components are declared per project in `Dovetail.toml` (see [Part 11: Packages](https://dovetaillang.org/book/packages.md)):

```toml
compiler-version = "0.1.4"

[[project]]
name = "myapp"
root_package = "app"
packages = ["."]

[[project.component]]
path = "artifacts/sqlite.wasm" # relative to the project directory
package = "sqlite.raw"          # the Dovetail package the bindings appear as
```

Use **`path`** to reference a component `.wasm` file inside its owning project directory. Commit the actual binary with the library so Git dependencies carry it automatically. The compiler does not bundle SQLite or other library components.

The `package` key chooses the Dovetail package name under which the generated bindings become importable. If the component exports more than one interface, pick one with `interface = "..."`.

Component dependencies are inherited: if your project depends on a library project that declares a component, you get the component (and its bindings) automatically — this is how `standard-sqlite` brings in the sqlite component for you.

---

## 17.2 What Gets Generated

At build time the compiler reads the component's WIT interface and injects a **generated bindings package** that you can `import` from like any package. Its source is written under `.dovetail/generated/` for editor navigation. The projection is mechanical:

| WIT construct | Dovetail declaration |
|---|---|
| `record` | `record` (fields 1:1, camelCase) |
| `variant`, `enum` | `enum` |
| `option<T>`, `result<T, E>` | `Option<T>`, `Result<T, E>` |
| `string`, `list<T>`, `tuple<...>` | `String`, `Array<T>`, tuples |
| `flags` | `newtype` over `Uint32` + constant functions |
| `resource` | `newtype` handle + a module of methods |

A WIT **resource** — an opaque handle owned by the component, like a database connection — becomes a `newtype` over `Int32` with a module of functions, so method-call syntax works. Every resource gets an explicit `drop`:

```dovetail
// Generated (virtual) package sqlite.raw — what the compiler injects:
public newtype Database = Int32

module Database =
    public function open(path: String, openFlags: Uint32): Result<Database, Int32> = ...
    public function prepare(self, sql: String): Result<Statement, Int32> = ...
    public function errmsg(self): String = ...
    public function drop(self): Unit = ...
```

The generated layer is deliberately **low-level and policy-free**: raw result codes, explicit handles, nothing renamed or reinterpreted. Ergonomics belong to wrapper libraries written in ordinary Dovetail — that separation keeps the generated layer stable while APIs evolve freely.

Calling a binding crosses the component boundary through the canonical ABI: values are *copied* between Dovetail's garbage-collected heap and the component's linear memory. The copy is what keeps the boundary safe — there is no shared mutable memory between your program and the component.

---

## 17.3 Using SQLite

For a Git dependency, select `standard-sqlite` through the standard-library shorthand described in [Part 11](https://dovetaillang.org/book/packages.md#115-github-dependencies):

```toml
compiler-version = "0.1.4"
standard-tag = "<tag>"

[[project]]
name = "myapp"
root_package = "app"
packages = ["."]
depends = ["standard-sqlite"]
```

Choose a tag whose manifest declares the matching compiler version. You can also select `standard-sqlite` in an explicit `[[dependencies]]` repository declaration. The library owns `artifacts/sqlite.wasm` and its component declaration; applications only need `depends = ["standard-sqlite"]`. Fetching the library brings the prebuilt binary, bindings, and macros transitively, without a SQLite build toolchain.

You rarely use `sqlite.raw` directly. The `standard-sqlite` library wraps it into an idiomatic API: connections and statements are **resources** (scoped with `use` — see [Part 13: Resources](https://dovetaillang.org/book/resources.md)), and every operation that touches the database engine is **async** (see [Part 12: Async](https://dovetaillang.org/book/async.md)):

**Complete example (checked in CI)** — `depends = ["standard-sqlite", "standard-io"]`:

<!-- book-example: {"name": "sqlite", "depends": ["standard-sqlite", "standard-io"]} -->
```dovetail
package sqlite

import standard.sqlite.Connection
import standard.sqlite.SqlValue
import standard.sqlite.SqliteError
import standard.io.Async

async function databaseExample(): Async<Unit, SqliteError> =
    let connection = use Connection.open(":memory:")
    await connection.execute("CREATE TABLE users (name TEXT)")
    let inserted = await connection.transaction<Int64, SqliteError>((transaction: Connection) =>
        transaction.executeWith("INSERT INTO users (name) VALUES (?1)", [|SqlValue.Text("alice")|])
    )
    assert inserted == 1i64
    let rows = await connection.query("SELECT name FROM users")
    assert rows.length == 1
    match rows.head[0] with
        case SqlValue.Text(name) => assert name == "alice"
        case _ => assert false

function main(): Unit = databaseExample().run()

test "a transaction inserts a parameterized row" = main()
```

The connection is closed automatically when the `use` scope ends — no manual `close` call, even on early error exits. The main pieces:

- **`Connection`** — `open` / `openWith` return `Resource<Connection, SqliteError>`; `execute` / `executeWith` run statements without result rows; `query` / `queryWith` / `queryOne` read; plus `lastInsertRowid`, `changes`, and `statement(sql)` (a prepared statement as a resource).
- **`SqlValue`** — a dynamically-typed cell: `Null`, `Integer(Int64)`, `Real(Float64)`, `Text(String)`, `Blob(Array<Uint8>)`. Used both for binding parameters (1-based, matching `?1`) and reading rows.
- **`SqliteError`** — every failure flows through the `Async` error channel, carrying the raw SQLite result code plus the connection's error message.
- **`PreparedStatement`** — for finer control: `use conn.statement(sql)`, then `bindAll`, `step` (async — this is where SQL executes), `row`, `reset`. Reuse one statement across executions with `reset`; it is finalized when its scope ends.

Today each operation completes synchronously under the hood (like the WASI filesystem behind `standard.io.fs`), but the async shape is the contract — code written this way keeps working unchanged when truly non-blocking hosts arrive.

Transactions are a combinator — commit on success, rollback on failure:

```dovetail
let outcome = await conn.transaction<Int64, SqliteError>((tx: Connection) =>
    tx.execute("INSERT INTO audit (event) VALUES ('signup')")
)
```

The example uses an in-memory database. With a file path instead of `":memory:"`,
the database is a normal SQLite file on the real filesystem — other tools (including the `sqlite3` CLI) can open it. One caveat from the WASI build: **only one process should use a database file at a time** (the build uses dot-file locking, and WAL mode is unavailable).

---

## 17.4 Building and Running

`dovetail build` produces one self-contained component: your code and every component dependency linked together, with only `wasi:*` imports remaining.

```bash
dovetail build myapp
dovetail run myapp
```

The in-memory example needs no filesystem grants. For a database file under the
working directory, use `dovetail run myapp --allow-cwd`. Other hosts must support
the artifact's Wasm features and imported WASI interfaces; WASI version support
alone does not guarantee compatibility. No sidecar SQLite component is needed at
runtime because it is composed into the built artifact.

---

## 17.5 Limits (v1)

The projection covers most WIT, with a few constructs rejected at build time with a clear error:

- imported interfaces must be **self-contained** — they may not `use` types from other WIT packages;
- async WIT types (`future`, `stream`) are not supported yet;
- `flags` with more than 32 flags, functions with more than 16 flattened parameters, and multi-named results are not supported.

Exporting Dovetail code *as* a component (so other languages can call you) is planned but not yet available.

---

## Summary

- A **component** is a self-describing `.wasm` library; its **WIT interface** is the contract Dovetail compiles against — WIT is Dovetail's FFI.
- Declare components in `Dovetail.toml` with `[[project.component]]`; `path` loads an artifact from its owning library project.
- The compiler injects a **virtual low-level bindings package** (resources = handle newtypes + `drop`); wrapper libraries like `standard-sqlite` provide the ergonomic API.
- `dovetail build` composes everything into one artifact; the runtime must provide compatible host interfaces and filesystem permissions.

In the next part, we'll tour the standard library.


---

# Part 18: Project Structure and Onion Architecture

Source: https://dovetaillang.org/book/project-structure/


A Dovetail workspace is a list of **projects**, and each project is a list of **packages**. That is a small amount of machinery, but it is enough to express — and, more importantly, to *enforce* — a full onion architecture for a bounded context or microservice.

This part describes a layout that has worked well in practice: how to split a bounded context into projects, how to layer the inside of the main project, which rules the compiler checks for you, and which ones remain your responsibility. Part 19 covers what goes *inside* those layers; this part is about where the walls are.

> **The one idea:** dependencies point **inward**. The domain layer knows nothing about the outside world; the outside world knows about the domain layer. Everything below is a mechanical consequence of that rule.

---

## 18.1 The Dependency Rule

Onion architecture (also called hexagonal, ports-and-adapters, or clean architecture) has a single rule:

> **Source-code dependencies may only point inward, toward the domain.**

Concentrically, from the inside out:

```
              ┌──────────────────────────────────┐
              │        infrastructure            │   SQL, HTTP, queues, clocks
              │   ┌──────────────────────────┐   │
              │   │      application         │   │   use cases, ports, jobs
              │   │   ┌──────────────────┐   │   │
              │   │   │     domain       │   │   │   entities, value objects,
              │   │   │                  │   │   │   invariants — no IO
              │   │   └──────────────────┘   │   │
              │   └──────────────────────────┘   │
              └──────────────────────────────────┘
                            ▲
                  dependencies point inward
```

The payoff is that the interesting part of your program — the rules of the business — never mentions a database, an HTTP framework, or a wire format. You can read it, test it, and change it without starting a container.

The rest of this part is about turning that picture into `Dovetail.toml` entries and directories.

---

## 18.2 Three Projects per Bounded Context

A bounded context (in a microservice deployment, one service) is **three projects**:

```
acme-workspace/
├── Dovetail.toml
├── shared-kernel/          ← shared across ALL contexts (17.8)
├── orders-primitives/      ← the context's value vocabulary
├── orders-contract/        ← the context's public wire surface
└── orders-app/             ← the context itself
    ├── src/
    │   ├── domain/
    │   ├── application/
    │   ├── infrastructure/
    │   └── main.dove     ← composition root
    └── test/
```

```toml
[[project]]
name = "orders-primitives"
root_package = "acme.orders.primitives"
depends = ["shared-kernel"]
packages = ["."]

[[project]]
name = "orders-contract"
root_package = "acme.orders.contract"
depends = ["shared-kernel", "orders-primitives", "standard-io"]  # Async, for service contracts
packages = ["."]

[[project]]
name = "orders-app"
root_package = "acme.orders"
depends = [
    "shared-kernel",
    "orders-primitives",
    "orders-contract",
    "standard-io",
    "standard-json",
]
packages = ["domain", "application", "infrastructure", "."]
```

### `primitives` — the value vocabulary

Value types with no identity and no lifecycle: `OrderId`, `Money`, `Quantity`, `Sku`, `Currency`. Newtypes and small records, with their invariants enforced at construction.

```dovetail
package acme.orders.primitives

public newtype OrderId private = String

module OrderId =
    public function parse(raw: String): Result<OrderId, String> =
        if raw.isEmpty then
            Error("order id must not be empty")
        else
            Ok(OrderId(raw))

    public function text(self: OrderId): String = self.value
```

Every layer may use `primitives`, and `primitives` may use nothing but the shared kernel. That is what makes it the *lowest* layer.

**Why does this project exist at all?** Because `contract` and `domain` must speak the same value vocabulary without either depending on the other. A REST response and an aggregate both need to say `OrderId`, but the contract must not import the domain (that would leak your model onto the wire) and the domain must not import the contract (that would point a dependency outward). Extracting the shared vocabulary downward is the standard fix for that kind of cycle, and `primitives` is that extraction, made permanent.

**What does not belong here:** anything with identity, anything with a lifecycle, anything that performs IO, and — the one people get wrong — **anything only one layer needs**. A value type the model uses and the contract never mentions belongs in the domain layer, not here. `primitives` is for the *shared* vocabulary; promote a type into it when a second layer needs to speak it, not before (19.2).

### `contract` — the public wire surface

Everything another context or an HTTP client is allowed to know: request and response shapes, integration events, public error codes, and enum-like status values as they appear on the wire.

```dovetail
package acme.orders.contract

import acme.orders.primitives.OrderId
import acme.orders.primitives.Money

public record PlaceOrderRequest =
    customerId: String
    lines: Array<OrderLineDto>

public record OrderPlaced =
    orderId: OrderId
    total: Money
    occurredAt: Instant
```

Two rules:

1. **The domain layer must not use it.** A contract type is a serialization concern; letting it into the model means every wire change becomes a model change.
2. **It is versioned by other people's code.** Other contexts compile against it. Treat every change as a breaking-change question, and keep its own dependencies minimal so consumers do not inherit a tree.

**Service contracts.** A contract is not always just data. When a context publishes an RPC-style surface — the set of calls it answers — that callable shape belongs in `contract` too, and it necessarily mentions `Async`:

```dovetail
package acme.orders.contract

public interface OrderService =
    function listOrders(self: Self, query: OrderQuery): Async<Array<OrderSummary>, OrderServiceError>
    function placeOrder(self: Self, request: PlaceOrderRequest): Async<OrderId, OrderServiceError>
```

So `orders-contract` does depend on `standard-io`, for the `Async` type. That is not a contradiction of the no-IO rule: **declaring** that an operation is asynchronous is not **performing** IO. The contract project still has no implementation, no sockets, no files, no `use`, and no `main`. It says what can be called; it never says how.

Three rules keep a service contract from becoming a back door into your model:

1. **Contract types on both sides.** `listOrders` returns `Array<OrderSummary>` — a DTO — never `Array<Order>`, the aggregate. The compiler already enforces this: `contract` cannot see `domain`, so an aggregate is not even nameable there. That constraint is a feature; it is the reason the wire surface stays a wire surface.
2. **Contract errors, not domain errors.** `OrderServiceError` is a wire-stable enum of outcomes a caller can act on. Domain errors are internal detail and will change as the model does.
3. **The interface is not the use case.** Implement it in `infrastructure` as a thin adapter that delegates to the application service, rather than having `PlaceOrderService` implement `OrderService` directly. The two signatures look identical on day one and diverge by month three — and if they are the same type, every wire-compatibility constraint your consumers impose is now a constraint on your use cases. (For a small context with a single consumer, collapsing them is a defensible shortcut; know that you are trading a mapping function for that coupling.)

The payoff appears in 18.9: because `OrderService` is an interface rather than a URL, the same contract can be implemented in-process when both contexts share a binary, or as an HTTP stub when they do not — and no caller can tell which.

`contract` remains a **library**: no `main`, no adapters, no IO of its own, and nothing a consumer cannot afford to compile against.

### `app` — the context itself

The deployable. It holds the three layers as three packages, plus a composition root, and it is the only project that produces a WASM component.

---

## 18.3 Three Packages Inside `app`

```toml
packages = ["domain", "application", "infrastructure", "."]
```

That line is not documentation. **Packages are typechecked in the order listed, each against the accumulated registry of the packages before it.** A package cannot import a package that appears later in the list — the name simply does not exist yet. Your layering is a compile error, not a code-review convention.

| Package | Directory | May see | Contains |
|---|---|---|---|
| `acme.orders.domain` | `src/domain/` | primitives, shared kernel | entities, aggregates, domain services, domain events, invariants |
| `acme.orders.application` | `src/application/` | + domain, contract | use cases, ports, event handlers, jobs |
| `acme.orders.infrastructure` | `src/infrastructure/` | + application | repository/ACL implementations, HTTP wiring, SQL, clients |
| `acme.orders` | `src/` | everything | the composition root and `main` |

### The domain package

Pure. Entities and aggregates, the invariants that hold them together, domain services for logic that belongs to no single entity, and domain events. It returns values and `Result`, never `Async`.

```dovetail
package acme.orders.domain

import acme.orders.primitives.OrderId
import acme.orders.primitives.Money
import acme.orders.primitives.Quantity

public enum OrderStatus =
    Draft
    Placed
    Cancelled

public class Order private (
    public id: OrderId,
    mutable status: OrderStatus,
    mutable lines: List<OrderLine>
) =
    public function place(self): Result<OrderPlacedEvent, OrderError> =
        match self.status with
            case OrderStatus.Draft =>
                if self.lines.length == 0 then
                    Error(OrderError.Empty)
                else
                    self.status = OrderStatus.Placed
                    Ok(OrderPlacedEvent(self.id, self.total()))
            case _ => Error(OrderError.AlreadyPlaced)
```

Note what is absent: no `Async`, no `await`, no repository, no logging, no `use`. `place` decides; it does not persist.

### The application package

Use cases. An application service loads aggregates through a port, calls into the domain, and persists the result. It is where a unit of work begins and ends, and it is the layer that publishes integration events.

It also **declares the ports** — the interfaces that the outside world must implement:

```dovetail
package acme.orders.application

import acme.orders.domain.Order
import acme.orders.primitives.OrderId

public interface OrderRepository =
    function findById(self: Self, id: OrderId): Async<Option<Order>, RepositoryError>
    function save(self: Self, order: Order): Async<Unit, RepositoryError>
```

Declaring the port here, next to its consumer rather than next to its implementation, is what inverts the dependency: `infrastructure` depends on `application` in order to implement it, so the arrow points inward even though the data flows outward at runtime.

```dovetail
public class PlaceOrderService(
    orders: OrderRepository,
    events: EventPublisher,
    clock: Clock
) =
    public async function handle(self, command: PlaceOrder): Async<OrderId, PlaceOrderError> =
        let found: Option<Order> = await self.orders.findById(command.orderId)
            .mapError((e: RepositoryError) => PlaceOrderError.Storage(e))
        let order: Order = found orReturn Async.fail(PlaceOrderError.NotFound)

        let event: OrderPlacedEvent = order.place() orReturn
            Async.fail(PlaceOrderError.Rejected(...))

        await self.orders.save(order).mapError(...)
        await self.events.publish(OrderPlaced { orderId = order.id, ... })
        order.id
```

The shape is always the same: **load, decide, persist, announce.** The decision — `order.place()` — is one line, and it is the only line that encodes a business rule. Everything around it is plumbing. If your application services start containing `if` statements about the business, that logic belongs in the domain.

### The infrastructure package

Everything the real world forces on you: SQL, HTTP, queues, files, clocks, retries. Two kinds of adapter live here.

**Driven adapters** implement the ports the application declared:

```dovetail
package acme.orders.infrastructure

import acme.orders.application.OrderRepository
import acme.orders.domain.Order

public class SqliteOrderRepository(connection: Connection) implements OrderRepository =
    public async function findById(self, id: OrderId): Async<Option<Order>, RepositoryError> =
        let rows = await self.connection.query("select ... where id = ?", [id.text()])
        rows.first().map((row: Row) => self.toDomain(row))

    // Mapping row -> aggregate lives here, never in the domain.
    function toDomain(self, row: Row): Order = ...
```

**Driving adapters** translate the outside world into use-case calls — HTTP routes, message consumers, CLI entry points:

```dovetail
public async function handlePlaceOrder(
    service: PlaceOrderService,
    request: HttpRequest
): Async<HttpResponse, Never> =
    let dto: PlaceOrderRequest = Json.decode<PlaceOrderRequest>(request.body) orReturn
        Async.succeed(HttpResponse.badRequest("malformed body"))
    ...
```

This is the layer where the contract types are read and written: the HTTP handler decodes a `PlaceOrderRequest`, turns it into a command, and encodes the result back. Contract types get no further inward than here and the application layer.

> **If the context grows,** split the driving adapters into their own package: `packages = ["domain", "application", "api", "infrastructure", "."]`. Because `api` is listed before `infrastructure`, the compiler will then guarantee your HTTP layer cannot reach for a concrete repository — it can only see the application's ports. Start with one `infrastructure` package; split when the SQL and the routing stop fitting in one head.

---

## 18.4 What the Compiler Enforces

It is worth being precise about which walls are real and which are agreements, because you will lean on the real ones.

**Enforced — package order.** As above: `domain` cannot name anything in `application` or `infrastructure`. Attempting it is an unresolved-name error.

**Enforced — project dependencies.** `depends` in `Dovetail.toml` must be a DAG, and it is checked. `orders-contract` cannot depend on `orders-app`, so your wire surface can never accidentally drag in your implementation.

**Enforced — visibility.** Dovetail has four levels, and the default is narrower than most people expect:

| Modifier | Visible from |
|---|---|
| `public` | any package that can see the declaring package |
| `internal` | the same package **only** (this is the default) |
| `private` | the declaring **file** only |
| `protected` | the declaring class and its subclasses |

Because `internal` is per-package and each layer is its own package, **a layer's helpers are invisible to the next layer unless you write `public`**. Each layer's surface is therefore an explicit choice. This works especially well in the domain layer: make the aggregate root `public` and everything it coordinates `internal`, and the application layer is structurally unable to reach past the root.

**Not enforced — "the domain layer has no IO," and "the domain layer does not use the contract."** `depends` is declared per *project*, so every package in `orders-app` can see every one of that project's dependencies. If `orders-app` depends on `standard-io` and `orders-contract` — and it must, for the outer layers — then `src/domain/` can import them too. Nothing stops it.

In practice this is a review rule and an easy one to check (`grep -r "^import standard.io" src/domain/`). If you would rather the compiler checked it, use the variant in the next section.

---

## 18.5 Variant: the Domain Layer as Its Own Project

Promote `domain` from a package to a project, and the two unenforced rules become enforced — because a project only sees what its own `depends` lists:

```toml
[[project]]
name = "orders-domain"
root_package = "acme.orders.domain"
depends = ["shared-kernel", "orders-primitives"]      # no io, no contract
packages = ["."]

[[project]]
name = "orders-app"
root_package = "acme.orders"
depends = [
    "shared-kernel",
    "orders-primitives",
    "orders-contract",
    "orders-domain",
    "standard-io",
    "standard-json",
]
packages = ["application", "infrastructure", "."]
```

```
orders-primitives/
orders-contract/
orders-domain/           ← cannot import standard.io: it is not a dependency
│   ├── src/
│   └── test/            ← its own IO-free test suite
orders-app/
    ├── src/application/
    ├── src/infrastructure/
    ├── src/main.dove
    └── test/
```

| | Three projects | Four projects |
|---|---|---|
| Layering inside `app` | enforced (package order) | enforced (package order) |
| Domain has no IO | convention | **enforced** |
| Domain cannot see the contract | convention | **enforced** |
| Domain tests | share the app's `test/` | own `test/`, no IO deps |
| Cost | — | one manifest entry, one directory |

The trade-off is small enough that the four-project layout is the better default for any context that will outlive its first release, and for any team large enough that "we agreed not to" is not a mechanism. Use three projects for a small context, a prototype, or a service you expect to stay under a few thousand lines — and note that promoting `domain` later is a directory move plus a manifest entry, since the package path `acme.orders.domain` is unchanged either way.

---

## 18.6 Ports and Adapters

A **port** is an [interface](https://dovetaillang.org/book/type-system.md#611-interfaces-and-interface-types) declared by the layer that *needs* the capability. These examples store ports in fields and pass them as values, so they use `interface`; a plain `trait` is usable only as a generic bound. An **adapter** is an implementation supplied by a layer further out. Two kinds matter here.

### Repositories

One repository per aggregate root, phrased in domain terms. Repository methods take and return **aggregates**, never rows, never DTOs:

```dovetail
public interface OrderRepository =
    function findById(self: Self, id: OrderId): Async<Option<Order>, RepositoryError>
    function save(self: Self, order: Order): Async<Unit, RepositoryError>
```

If a method on your repository returns `OrderSummaryDto` for a screen, it is not a repository — it is a query service. Give it its own port (`OrderQueries`) and let it return contract types directly, bypassing the domain. Read models and write models diverge for good reasons; do not force the aggregate to serve both.

### The anti-corruption layer

An ACL is a port whose implementation talks to *another bounded context* and translates its vocabulary into yours. The port is phrased entirely in your terms:

```dovetail
package acme.orders.application

import acme.orders.domain.Buyer
import acme.orders.primitives.CustomerId

public interface BuyerLookup =
    function fetch(self: Self, id: CustomerId): Async<Option<Buyer>, LookupError>
```

The implementation is where the other context's language appears — and stops:

```dovetail
package acme.orders.infrastructure

import acme.customers.contract.CustomerResponse   // the ONLY place this is imported
import acme.orders.application.BuyerLookup
import acme.orders.domain.Buyer

public class HttpBuyerLookup(client: HttpClient) implements BuyerLookup =
    public async function fetch(self, id: CustomerId): Async<Option<Buyer>, LookupError> =
        let response: CustomerResponse = await self.client.getJson(...)
        Some(Buyer(id, response.displayName, response.billingCountry))
```

That translation step is the entire point. `Buyer` is *your* notion of a customer — the two or three facts the Orders context needs — not the sixty fields the Customers context tracks. Without the ACL, their model becomes your model, and their next release becomes your next release.

---

## 18.7 The Composition Root

Someone has to know the concrete types. That someone is `main`, in the project's root package (`src/`, listed last in `packages`), and **nowhere else**.

```dovetail
package acme.orders

import acme.orders.application.PlaceOrderService
import acme.orders.infrastructure.SqliteOrderRepository
import acme.orders.infrastructure.HttpBuyerLookup
import acme.orders.infrastructure.OutboxPublisher

async function run(): Async<Unit, StartupError> =
    let connection = use Sqlite.open("orders.db")
    let httpClient = use HttpClient.make()

    let repository: OrderRepository = SqliteOrderRepository(connection)
    let buyers: BuyerLookup = HttpBuyerLookup(httpClient)
    let publisher: EventPublisher = OutboxPublisher(connection)

    let placeOrder = PlaceOrderService(repository, publisher, buyers)

    await Http.serve(8080, routes(placeOrder))

function main(): Unit = Async.run(run())
```

Three properties make this the right shape:

- **It is the only place `use` appears for long-lived resources.** The connection pool, the HTTP client, and the log sink are acquired here and released in LIFO order when `run` returns — including on failure and on interruption (Part 13).
- **It is the only place a concrete adapter is named.** Swapping SQLite for Postgres, or a real buyer lookup for an in-memory fake, is an edit to this file only.
- **It has no logic.** If a condition appears here that is not configuration, it belongs in the application layer.

There is no dependency-injection container, and none is needed: the composition root is the container, it is ordinary code, and its mistakes are compile errors.

---

## 18.8 The Shared Kernel

`primitives` shares a vocabulary between the layers of one context. The **shared kernel** shares one between *contexts*:

```toml
[[project]]
name = "shared-kernel"
root_package = "acme.kernel"
packages = ["."]
```

Same idea, much larger blast radius — and that difference should govern what you put in it.

**What belongs:** value types and their invariants, where the meaning is genuinely identical everywhere. `Money`, `Currency`, `Percentage`, `DateRange`, `EmailAddress`, `CountryCode`. Cross-context identifier newtypes: `CustomerId`, `TenantId`. Small, total, dependency-free.

**What does not belong:**

- **Anything with IO or `Async`.** The kernel sits below every domain layer; it must be as pure as they are.
- **Anything only one context uses.** Push it down into that context's `primitives`.
- **Repositories, services, ports.** Those are per-context by definition.
- **Entities.** This one is worth arguing.

### Do not share entities

It is tempting to define `Customer` once and have Orders, Billing, and Shipping all use it. Resist that, for two reasons.

The mechanical one: an entity has identity **and a lifecycle**, and that lifecycle is owned by exactly one context. Sharing the type shares the lifecycle. A rule Billing adds about delinquent accounts is now compiled into Orders, and every context must be redeployed and re-reasoned together — which is the coupling that having bounded contexts was meant to remove.

The conceptual one, which is the deeper point: **"customer" does not mean the same thing in the two contexts.** To Orders, a customer is a shipping address and a credit status. To Billing, a customer is a tax jurisdiction, a payment instrument, and an invoice history. A shared `Customer` becomes the union of every context's needs — an entity with forty fields of which each caller uses four, whose invariants must satisfy everyone and therefore constrain no one.

The alternative is smaller and better:

- Put **`CustomerId`** in the shared kernel. The identity *is* the same thing everywhere; that is precisely what makes it shareable.
- Let each context define its own model of a customer — Orders has `Buyer`, Billing has `Payer` — containing only what that context needs.
- Populate it through the ACL (18.6) from the owning context's contract.

Two contexts modelling the same real-world thing differently is not duplication to be eliminated. It is the reason bounded contexts exist.

### Governing the kernel

Every context compiles against the shared kernel, so a change to it is a change to all of them. Three habits keep that from hurting:

1. **Keep it small.** If you are unsure whether something belongs, it does not. Duplicating a value type into two contexts costs far less than a shared type that fits neither.
2. **Changes need agreement from every consumer.** This is a real cost, and it is the reason the kernel should be slow-moving by design.
3. **When a type grows context-specific behavior, copy it down.** The moment `Money` needs a `roundForTaxJurisdiction` that only Billing uses, Billing gets its own `Money` extension in its own `primitives` — or its own type.

---

## 18.9 Talking to Other Bounded Contexts

The workspace-level rule that keeps a multi-context repository from turning into a ball of mud:

> **A context may depend on another context's `contract` project and on the shared kernel. Never on its `app`, and never on its `domain`.**

```toml
[[project]]
name = "orders-app"
depends = [
    "shared-kernel",
    "orders-primitives",
    "orders-contract",
    "customers-contract",     # ✅ another context's wire surface
  # "customers-app",          # ❌ never
]
```

`customers-contract` is the same artifact whether the two contexts run in one process or on opposite sides of a network — which is what makes extracting a context into a separate service a deployment change rather than a rewrite. The dependency is already narrowed to the wire surface; only the transport underneath it changes.

### Service contracts, client stubs, and the ACL

If the Customers context publishes a service contract (18.2), a consumer ends up with two interfaces, and it is worth being clear about why neither one is redundant:

```dovetail
// acme.customers.contract — what the OWNER publishes. Their vocabulary, their granularity.
public interface CustomerService =
    function getCustomer(self: Self, id: CustomerId): Async<Option<CustomerResponse>, CustomerServiceError>

// acme.orders.application — what the CONSUMER needs. Your vocabulary, your granularity.
public interface BuyerLookup =
    function fetch(self: Self, id: CustomerId): Async<Option<Buyer>, LookupError>
```

Between them sits the consumer's infrastructure, holding both halves:

```dovetail
package acme.orders.infrastructure

import acme.customers.contract.CustomerService
import acme.customers.contract.CustomerResponse
import acme.orders.application.BuyerLookup

// 1. The client stub: implements the owner's contract over a transport.
public class HttpCustomerClient(client: HttpClient, baseUrl: Url) implements CustomerService = ...

// 2. The ACL: implements YOUR port by calling theirs, and translates.
public class CustomerServiceBuyerLookup(customers: CustomerService) implements BuyerLookup =
    public async function fetch(self, id: CustomerId): Async<Option<Buyer>, LookupError> =
        let response: Option<CustomerResponse> = await self.customers.getCustomer(id)
            .mapError((e: CustomerServiceError) => LookupError.Upstream(e))
        response.map((r: CustomerResponse) => Buyer(id, r.displayName, r.billingCountry))
```

The stub is a **transport** concern and the ACL is a **translation** concern, and keeping them apart is what buys you the deployment flexibility:

- **Contexts co-deployed?** Wire the ACL to the Customers app's own implementation of `CustomerService` directly — no HTTP, no serialization, no stub. Every call becomes a function call.
- **Contexts split across the network?** Wire the ACL to `HttpCustomerClient` instead.

The change is one line in the composition root. Nothing in the application layer, and nothing in the domain, knows which world it is running in.

The consumer's application layer depends only on `BuyerLookup`. Do not let it import `CustomerService` — that would put the owner's vocabulary and the owner's release schedule into your use cases, which is the exact coupling the ACL exists to prevent.

### Integration events

Integration events are the other half of the contract: they are how a context announces facts without anyone asking. They are declared in `contract`, published by the **application** layer through a port, and delivered by **infrastructure**.

```dovetail
// contract: the fact, in wire terms
public record OrderPlaced =
    orderId: OrderId
    total: Money
    occurredAt: Instant

// application: the port
public interface EventPublisher =
    function publish(self: Self, event: OrderPlaced): Async<Unit, PublishError>

// infrastructure: transactional outbox, Kafka, whatever it turns out to be
public class OutboxPublisher(connection: Connection) implements EventPublisher = ...
```

Do not confuse these with **domain events**. A domain event (`OrderPlacedEvent`, returned by `Order.place()` in 18.3) lives in the domain layer, is phrased in domain types, and **never leaves the context**. The application layer translates the ones that matter into integration events. Keeping the two separate is what lets you refactor your model without breaking every subscriber; Part 19 goes into the distinction in depth, and Part 21 into how consumers should receive them.

---

## 18.10 Testing the Layers

Each project has its own `test/` directory at the project root, and test packages are granted internal access to every source package in that project — so tests can reach a layer's `internal` helpers without you widening them to `public` for testing's sake.

```
orders-domain/test/    placeOrderTest.dove      pure, fast, no fakes
orders-app/test/       applicationTest.dove     services against in-memory ports
                       infrastructureTest.dove  real SQLite, real HTTP
```

The layering pays off directly in the test suite:

- **Domain tests** construct an aggregate, call a method, and assert on the result. No mocks, no async, no setup. These should be the overwhelming majority of your tests and should run in milliseconds.
- **Application tests** instantiate a service with in-memory adapters. Because ports are interfaces, an `InMemoryOrderRepository` backed by an array is a few lines and needs no mocking framework. These verify orchestration: was the event published, was the aggregate saved.
- **Infrastructure tests** are the only ones that touch a real database or socket. They are slower and fewer, and they verify the adapter, not the business rule.

```dovetail
package test

import acme.orders.domain.Order
import acme.orders.primitives.OrderId

test "placing an empty order is rejected" =
    let order = Order.draft(OrderId("o-1"))
    assert order.place().isError()
```

Note what this test does not need: no database, no runtime, no `Async`. That is the whole return on the dependency rule — and if a dovetail test *does* need those things, you have found IO that leaked inward.

---

## 18.11 Rules at a Glance

| Rule | Enforced by |
|---|---|
| `domain` cannot see `application` or `infrastructure` | package order in `Dovetail.toml` |
| `contract` cannot see `app` | project `depends` (DAG) |
| A layer's internals are hidden from the next layer | `internal` is the default, and is per-package |
| No dependency cycles anywhere | the compiler |
| `domain` has no IO | project `depends` (four-project layout) or review |
| `domain` does not use `contract` | project `depends` (four-project layout) or review |
| Only `main` names concrete adapters | review — and it is obvious when violated |
| A service contract cannot expose an aggregate | `contract` cannot see `domain` |
| Cross-context deps go through `contract` only | project `depends` |

And the shapes worth memorizing:

- **Ports point inward.** The interface is declared where it is *used*, implemented where the technology lives.
- **Application services read: load, decide, persist, announce.** The decision is a domain call.
- **Repositories speak aggregates.** Rows and DTOs stop at the infrastructure boundary.
- **Declaring `Async` is not doing IO.** A service contract may return `Async`; it may not contain an implementation.
- **The composition root is the only place that knows everything.** Keep it dumb and keep it small.

---

## Summary

- A bounded context is **three projects** — `primitives`, `contract`, `app` — plus an optional fourth if you promote `domain` out of `app` to have the compiler enforce its purity.
- `primitives` exists so `contract` and `domain` can share a vocabulary without depending on each other; the **shared kernel** does the same thing across contexts.
- Inside `app`, the layers are packages, and **the order in `packages = [...]` enforces the layering** — inner layers physically cannot name outer ones.
- **Ports are interfaces declared by the inner layer** and implemented by the outer one; that inversion is what makes the dependency rule survive contact with a database.
- **The composition root** (`main`, in the root package) is the only code that names concrete adapters or acquires long-lived resources.
- Share **value types and IDs** across contexts, never entities — the same word legitimately means different things in different contexts, and the ACL is where the translation lives.
- Cross-context dependencies go through `contract` and nothing else, which is what makes splitting a context into its own service a deployment change rather than a rewrite.

Part 19 turns to what fills these layers: aggregates, entities, value objects, domain events, and how to model a business rule so it has exactly one home. Part 20 covers the application layer that drives them — use cases, event handlers, and jobs. Part 21 zooms back out to the relationships *between* contexts: when to consume another context's `contract` directly, when to insulate yourself behind an anticorruption layer, and how that choice shows up in your `Dovetail.toml`.


---

# Part 19: The Domain Layer

Source: https://dovetaillang.org/book/ddd/


Part 18 built the walls. This part is about what goes inside the innermost one: the model — the types that carry your business rules.

Everything here lives in the `domain` package (or the `orders-domain` project, if you took the four-project layout of 18.5). That means everything here is **pure**: no `Async`, no `await`, no `use`, no repository, no logging. A domain function takes values and returns values. If it cannot decide with what it was handed, it says so by returning an error.

Part 20 covers the layer that drives this one — use cases, event handlers, jobs, and the repository ports that load and store what you build here. Part 21 zooms out to other contexts.

> **The one idea:** model with types until most of your rules *cannot* be broken, then give the rules that remain exactly one home.

Those two halves are in that order deliberately. A rule enforced by a type is checked everywhere, by the compiler, forever. A rule enforced by a function is checked wherever someone remembers to call it. Dovetail has a strong type system; the whole point of this chapter is to spend it.

---

## 19.1 Start With the Types

Dovetail separates a type's **declaration** from its **behavior**: a record says what the shape is, and a `module` of the same name says what it does. Lean into that. Put the entire model's vocabulary in one file, and the behavior in a file per concept:

```
orders-dovetail/src/
├── types.dove        every record, enum, and newtype in the model
├── Order.dove        module Order — the aggregate's behavior
├── Shipment.dove     module Shipment — a second aggregate
└── policy.dove       domain services and policies
```

This is the first recommendation in the chapter because it is the one that changes how you work, not just how your files are arranged.

It does assume the **functional style** of 19.5, which is what the rest of this chapter is written in. The layout works because a record separates shape from behavior, so the shapes can be collected without dragging the functions along. A class does not separate them, and is not meant to — see 19.5 for what an object-oriented model organizes by instead.

### Why one types file

**Because the types file *is* the model.** Everything else in the domain layer is consequence. When the shapes are collected in one place, you can read the entire model in one sitting — states, parts, errors, events — and that turns it into an artifact you can actually use: something to review, to walk through with a domain expert, to hand a new joiner, and to diff when the business changes. A model change *should* be a visible edit in one file, not a shift scattered across twelve.

**Because it is where the modelling happens.** The habit this layout encourages is to write the types first and the behavior second — to spend your thinking on what states exist and what each one carries, before writing a single function. That is the work. 19.2 is entirely about doing it well, and it is much easier to do when you are looking at the whole vocabulary at once rather than at one record in one file.

**Because mutual references are free.** All files in a package are typechecked together, so `Order` may mention `OrderLine`, `OrderStatus`, and `OrderPlaced` in any order, with no forward declarations and no dependency ordering to maintain. There is nothing pushing you to split.

**Because the behavior files stay about behavior.** `Order.dove` reads as a list of the things an order can do, uninterrupted by field declarations.

---

## 19.2 Make Illegal States Unrepresentable

This is the section the rest of the chapter rests on.

Most "business rules" are not really rules. They are statements about which combinations of data make sense — and a statement about which combinations make sense is a **type**. Every one you can express as a type is a rule that cannot be violated, cannot be forgotten at a call site, and needs no test.

### The model most people write first

```dovetail
public enum OrderStatus =
    Draft
    Placed
    Cancelled

public record Order =
    id: OrderId
    customerId: CustomerId
    status: OrderStatus
    lines: List<OrderLine>
    placedAt: Option<Instant>
    total: Option<Money>
    cancelledAt: Option<Instant>
    cancellationReason: Option<CancellationReason>
```

This looks reasonable, and it is what a database table would suggest. Count what it permits: three statuses times four independent optional fields is **48 representable combinations**, of which perhaps three make sense. The rest are all constructible, and the compiler is happy with every one of them:

- a `Draft` with a `placedAt`
- a `Placed` order with no `total`
- an order that is `Cancelled` but has a `placedAt` and no `cancelledAt`
- an order with both a cancellation reason and a `Draft` status

Worse than the nonsense states is what they do to every function you write afterwards. `total` is an `Option<Money>` in all three states, so *every* caller must handle `None` — including callers that only ever see placed orders, where `None` is impossible. You end up with `.require` sprinkled through the model, or a defaulted zero that quietly becomes a wrong invoice.

The status enum here is not modelling anything. It is a label sitting next to the data, and keeping them consistent is now your job, forever, in every function.

### The model to write instead

Put the data **inside the state that gives it meaning**:

```dovetail
public record Placement =
    placedAt: Instant
    total: Money

public record Cancellation =
    cancelledAt: Instant
    reason: CancellationReason

public enum OrderStatus =
    Draft
    Placed(Placement)
    Cancelled(Cancellation)

public record Order private =
    id: OrderId
    customerId: CustomerId
    status: OrderStatus
    lines: List<OrderLine>
```

Now there are **exactly three representable states**, and each carries precisely what that state means:

- A `Draft` has no placement. Not an empty one, not a `None` — there is no field to be wrong about.
- A `Placed` order *always* has a `placedAt` and a `total`. Both are plain values, not `Option`, because in this state their absence is not a possibility.
- A `Cancelled` order always has a reason.

The nonsense states are gone — not caught, *gone*. There is no code that rejects them because there is no way to write them down. Try to read a placement off a draft and the compiler stops you before you finish the thought:

```dovetail
match order.status with
    case OrderStatus.Draft(placement) => ...
```
```
error: variant 'OrderStatus.Draft' has no fields;
       use 'OrderStatus.Draft' without parentheses
```

And reading the value requires proving you are in the state that has it:

```dovetail
    public function placedAt(self): Option<Instant> =
        match self.status with
            case OrderStatus.Placed(placement) => Some(placement.placedAt)
            case _ => None
```

The `Option` appears exactly once, at the boundary where it is honest — asking a possibly-unplaced order when it was placed — instead of infecting the four fields underneath.

### Naming the payload, or inlining it

A variant can carry its fields directly, with no separate record:

```dovetail
public enum OrderStatus =
    Draft
    Placed { placedAt: Instant, total: Money }
    Cancelled { cancelledAt: Instant, reason: CancellationReason }
```

built with `OrderStatus.Placed { placedAt = now; total = total }` and read by naming the fields in the pattern:

```dovetail
    public function placedAt(self): Option<Instant> =
        match self.status with
            case OrderStatus.Placed { placedAt = at; total = _ } => Some(at)
            case _ => None
```

Both forms model exactly the same three states — this is a question of whether the payload deserves a name, not of how much the type can prove.

**Giving the payload a name preserves the brace syntax.** With the named declaration `Placed(Placement)`, the same construction and field pattern still work:

```dovetail
let status = OrderStatus.Placed { placedAt = now; total = total }

match status with
    case OrderStatus.Placed { placedAt = at; total = _ } => Some(at)
    case _ => None
```

The construction means `OrderStatus.Placed(Placement { placedAt = now; total = total })`. The pattern means `OrderStatus.Placed(Placement { placedAt = at, total = _ })`. This lets you extract an inline payload into a named record without rewriting callers that construct or inspect its fields.

When a caller needs the concept as a whole, the positional form binds the actual record:

```dovetail
match status with
    case OrderStatus.Placed(placement) => Some(placement)
    case _ => None
```

Both forms remain available. Braces inspect the record's fields; parentheses bind or pass the `Placement` value. The shorthand applies to exactly one record payload, including a generic record whose type is known. It does not unwrap newtypes, classes, or multiple positional payloads. Patterns may omit fields, so `case OrderStatus.Placed { placedAt = at }` is sufficient when only the timestamp matters; there is no need for a rest marker.

**Inline** when the fields only ever exist as part of that state. It is two fewer types in `types.dove`, and the enum reads as the whole story of the state machine.

**A named record** when the payload is a concept in its own right — something you pass to a function, return, store, or want to say in a signature. `Placement` is one: 19.7 builds it as a value before putting the order into the state that holds it, and a function can take a `Placement` without taking an `Order`. Once you find yourself writing the same field list in two places, it has already earned the name.

Apply that test **per variant, not per enum** — one state's payload earning a name says nothing about its neighbours'. `OrderStatus` in 19.12 ends up mixed for exactly this reason: `AwaitingApproval(Money)` carries a bare total that means nothing outside the state, while `Approved(Approval)` names a payload the approval rules pass around. The rest of this chapter uses named payloads because `Placement` and `Cancellation` both earn one.

### Rules of thumb

**A field that only means something in one state belongs inside that state.** This is the whole technique, and `placedAt` is the archetype: it exists once an order is placed, and asking for it before then is not a missing value, it is a meaningless question.

**`Option` means "optional in every state", not "filled in later".** If a field becomes populated at a transition, it belongs to the state the transition produces. A middle name is genuinely optional; a shipment date is a state.

**Two booleans that cannot both be true are an enum.** `isPlaced` and `isCancelled` gives you four combinations for three states, and one of them is a bug you will eventually ship.

**A collection with a minimum size is not a plain list.** If a placed order must have at least one line, the honest type says so; `List<OrderLine>` cannot. So the rule ends up in `place` as a check that can refuse (19.7) — which is fine, but notice it is the type system telling you where a rule leaked out into a function.

### Errors are types too

The same discipline applies to refusals. An error enum whose variants are bare names throws away everything the code knew at the moment it refused:

```dovetail
public enum OrderError =
    NoLines
    NotDraft(OrderStatus)
    TooManyLines(Int32)
    MixedCurrency(Currency, Currency)
    CreditRefused
    ApprovalRequired(Money)
```

`NotDraft(OrderStatus)` carries what the order *actually* was, so the caller can say "this order was cancelled on the 3rd" instead of "not a draft". `MixedCurrency(Currency, Currency)` names both offenders. `ApprovalRequired(Money)` reports the total that tripped the threshold, so the message writes itself and the application layer can route the approval without going back to look.

The rule: **an error should carry the evidence for itself.** If reporting it well requires re-deriving what happened, the variant is missing a field.

### The compiler as reviewer

The payoff arrives on the day the business adds a state. Add `Refunded(Refund)` to `OrderStatus` and every exhaustive `match` in the codebase stops compiling — each one a place where somebody has to decide what a refunded order means. That is a review checklist generated by the compiler, complete and free.

This is why a bare `case _ =>` catch-all is worth being suspicious of in the domain layer. It buys you a little brevity today and costs you exactly the compile errors you would have wanted tomorrow. Match the states explicitly, and let the additions find you.

### How far to take it

You can go further. **Typestate** gives each state its own type — `DraftOrder`, `PlacedOrder` — so that `place` only exists on a draft and calling it twice is not a runtime error but a nonexistent function.

That is genuinely stronger, and for most models it is too much. You get a type per state, conversions at every boundary, and a repository that has to return a sum type anyway, since a row's state is not known until it is read. The enum-with-payloads is the sweet spot: it eliminates the illegal *combinations*, which is where the bugs actually live, while keeping one type you can load, store, and pass around.

Reach for typestate when a wrong transition is catastrophic rather than merely wrong — a payment capture, a compliance hold, a released deployment — and accept the ceremony for those.

---

## 19.3 Value Objects

A **value object** is defined by its value, not by identity. Two amounts of 12.50 USD are the same amount; there is no "which one." Value objects have no lifecycle, and they never change.

### Where they live

**Default to the domain package.** Most value objects are nobody else's business — an `OrderLine`, a `DiscountBand`, a `PickingPriority`. They go in `types.dove` with everything else.

**Promote one to `primitives` when a second layer needs to speak it** — in practice, when it appears on the wire. That is what `primitives` is for (18.2): it exists so `contract` and `domain` can share a vocabulary without either depending on the other. A type only the model uses creates no such pressure, so putting it there buys nothing and widens a surface other code compiles against.

`OrderId`, `Sku`, `Money`, and `Quantity` are in `primitives` below because the contract carries them. Had they been internal to the model, they would live in the domain package and nothing else would change.

That is the same rule at every boundary: **put a type at the innermost place that needs it, and promote only when a second consumer appears.** Domain-only stays in `domain`; shared with the contract moves to `primitives`; shared with another context moves to the shared kernel (18.8). Promotion is cheap — move the file, change the `package` line — which is precisely why starting inward costs nothing.

### Make invalid values unconstructable

19.2 removed illegal *combinations*. The same idea one level down removes illegal *values*: a private newtype and a module function that can refuse construction.

```dovetail
package acme.orders.primitives

public newtype OrderId private = String

module OrderId =
    public function parse(raw: String): Result<OrderId, String> =
        if raw.isEmpty then
            Error("order id must not be empty")
        else
            Ok(OrderId(raw))

    public function text(self): String = self.value

public newtype Sku private = String

module Sku =
    public function parse(raw: String): Result<Sku, String> =
        if raw.length != 8 then
            Error("sku must be exactly 8 characters")
        else
            Ok(Sku(raw))

    public function text(self): String = self.value
```

`private` after the newtype name is what makes this real. Outside `module Sku` in the defining package, even elsewhere in that same package, `Sku("nope")` is a compile error — *cannot construct private newtype 'Sku' outside its associated module*. Only that module can read `.value` or unwrap a constructor pattern; callers use `text()`. Trait implementations and extensions must use these module functions too. The only public construction path here is `parse`, so **once you hold a `Sku` it is valid**, and no code downstream ever checks again.

### Push behavior onto the value

A value object with no methods is a tooltip. Behavior that belongs to the value goes on the value:

```dovetail
@derive(Equatable)
public enum Currency =
    Usd
    Eur

public enum MoneyError =
    CurrencyMismatch

public record Money =
    minorUnits: Int64
    currency: Currency

module Money =
    public function of(minorUnits: Int64, currency: Currency): Money =
        Money { minorUnits = minorUnits; currency = currency }

    public function add(self, other: Money): Result<Money, MoneyError> =
        if self.currency != other.currency then
            Error(MoneyError.CurrencyMismatch)
        else
            Ok(Money {
                minorUnits = self.minorUnits + other.minorUnits
                currency = self.currency
            })

    public function times(self, quantity: Quantity): Money =
        Money {
            minorUnits = self.minorUnits * quantity.count().toInt64()
            currency = self.currency
        }
```

`add` returns a `Result` because adding USD to EUR is not an arithmetic operation, it is a bug — and the type says so. When money is an `Int64`, every `+` in the codebase is a place where the currencies could have differed and nobody checked.

`minorUnits` is the other decision worth making once: money as a floating-point number is a rounding bug waiting for a large enough invoice.

### When to introduce one

**Default to yes.** A bare `String` or `Int32` in a domain signature is a smell — not an error, but worth a second look every time, because it is the shape a rule takes before anyone has noticed it is a rule. `Quantity` not `Int32`, because quantities are positive. `Sku` not `String`, because SKUs have a shape. `Money` not `Int64`, because 500 of what?

The immediate payoff is that argument-order mistakes stop compiling. Given `function priceFor(sku: Sku, quantity: Quantity): Money` you cannot swap the arguments, which you very much can when they are `String` and `Int32`.

**The delayed payoff is the bigger one, and it is why this is a smell rather than a preference.** The rule usually arrives *after* the field does. Nobody says "SKUs are eight characters" on day one; it turns up in the third sprint, in a bug report. If `Sku` is a `String`, that rule has nowhere to live, so it lands in whichever function noticed first — and then in a second one, written by someone who did not know about the first, and the two drift. If `Sku` is a type, there is exactly one place the rule can go, and the day it goes there every value in the system is already validated.

By then the primitive is also **too late to tighten**. `String` is in two hundred signatures and nothing distinguishes the ones that meant a SKU, so the change you want is not a change you can make. The type costs six lines on the day you have no rules to put in it, which is precisely the day it is cheap.

**The exceptions are narrow.** Inside a value object's own representation — `Money.minorUnits` is an `Int64`, and the wrapper is the whole point. And genuinely free text with no unit and no rule, such as a customer's note. Everything else earns a type.

Conventions: `parse` when construction can fail, `make` when it cannot, never `new` or `create`.

---

## 19.4 Entities

An **entity** is defined by identity over time. An order that has had ten lines added and one removed is still that order. Two orders with identical contents are still two different orders.

- **The identity is a value object** — `OrderId`, not `String` — so it cannot be confused with a `CustomerId`.
- **The ID comes from outside.** Generating it inside the entity means randomness or a clock, and both are IO. An adapter supplies it, so the domain stays pure and deterministic. The same goes for timestamps: `place` takes `now` as a parameter (19.8).
- **Every change goes through a function that can refuse.** No setters, and no assembling a new version by hand from outside the module.
- **An entity is not automatically an aggregate root.** `OrderLine` has identity within its order but no independent existence; only roots get repositories (19.6).

### Make the transition boundary enforceable

The recommended declaration in 19.2 is `public record Order private = ...`. The type and its fields remain visible, so a caller can read `order.status`, inspect `order.lines`, and match the record. Construction and `with` updates belong exclusively to `module Order` in the defining package. The type can stay in `types.dove` and its module in `Order.dove`; file placement does not change that ownership.

This makes the entity rule enforceable: callers must use `Order.draft`, `order.addLine(...)`, and `order.place(...)`. Writing `order with { status = OrderStatus.Placed(...) }` from application code is a compile error. Trait implementations and extensions must use those functions as well.

`OrderStatus` remains publicly constructible in this model. Building a status value does not let a caller install it in a private `Order`. If the status needs its own construction rules, declare `enum OrderStatus private = ...` and put its factories in `module OrderStatus`; even `module Order` must then call those factories. Enum patterns remain available either way. Private records and enums expose inspection; private newtypes also hide their wrapped value.

The same boundary applies to named record payload shorthand. If `Placement` has a private constructor, `OrderStatus.Placed { placedAt = now; total = total }` must be inside `module Placement`, because it constructs a `Placement`. `OrderStatus.Placed(placement)` can wrap an existing value without constructing another record. Either pattern form remains available for inspection. If `OrderStatus` also has private construction, its permission is checked independently: being inside one type's module does not grant construction access to the other.

---

## 19.5 Two Styles: Values or Objects

**Record fields cannot be reassigned.** Referenced arrays or classes can still
contain mutable state; record immutability is shallow. Classes can carry mutable state. So this is not a per-type decision — it is a choice about what the whole domain layer is written in:

- **Functional.** Aggregates are records. A rule is a function from a value to a new value.
- **Object-oriented.** Aggregates are classes. A rule is a method that changes the object in place.

Pick one for the entire layer. A model where half the aggregates are values and half are objects is the worst of both, because every reader has to check which kind they are holding.

**This chapter recommends the functional style**, and is written in it.

### The functional model

```dovetail
module Order =
    public function draft(id: OrderId, customerId: CustomerId): Order =
        Order {
            id = id
            customerId = customerId
            status = OrderStatus.Draft
            lines = List<OrderLine>.Nil
        }

    public function addLine(self, line: OrderLine): Result<Order, OrderError> =
        match self.status with
            case OrderStatus.Draft =>
                if self.lines.length >= maxLines then
                    Error(OrderError.TooManyLines(maxLines))
                else
                    Ok(self with { lines = self.lines.prepend(line) })
            case other => Error(OrderError.NotDraft(other))
```

A rule that refuses returns `Error`; a rule that succeeds returns the next `Order`. The `with` expression keeps that from being a wall of field copies.

Note the shape of that `match`: because the state machine is an enum (19.2), the guard *is* the state check, and the failure case gets the actual status to report. In a model with a bare status field this would be `if self.status != OrderStatus.Draft`, and the error would have nothing to say.

Why this is the better default in Dovetail:

- **It matches everything else about the language.** No exceptions, rules returning `Result`, a layer with no IO, modules that already separate shape from behavior. `Result<Order, OrderError>` is the same shape as every other fallible operation and composes with `andThen` and `orReturn` like they all do.
- **Immutable contents make sharing safe.** An `Order` made entirely of immutable
  values can be shared without another function changing it. An array or mutable
  class stored in a record can still be changed through an alias.
- **The previous value is still there** — for comparing before and after, auditing what changed, retrying from a known state, or replaying history. Event sourcing stops being an architecture and becomes the natural reading of the model.
- **The tests are stronger.** You can assert both that the operation produced what it should and that its input was left alone (19.11).

The cost, named honestly: an operation that both advances the aggregate and reports a fact must return both, as a tuple (19.7).

### The object-oriented model

```dovetail
public class Order private (
    public id: OrderId,
    public customerId: CustomerId,
    mutable status: OrderStatus,
    mutable lines: List<OrderLine>
) =
    public function draft(id: OrderId, customerId: CustomerId): Order =
        Order(id, customerId, OrderStatus.Draft, List<OrderLine>.Nil)

    public function addLine(self, line: OrderLine): Result<Unit, OrderError> =
        match self.status with
            case OrderStatus.Draft =>
                self.lines = self.lines.prepend(line)
                Ok(())
            case other => Error(OrderError.NotDraft(other))
```

Two details are worth pointing out: `private` on the constructor means only `Order.draft` can build one, and class members are private unless marked `public`, so `status` and `lines` are not readable from outside at all.

Everything in 19.2 applies unchanged here — the state machine is still an enum carrying its data. The style choice is about mutation, not about how well you model.

### It changes the file layout

**19.1's `types.dove` does not apply to this style, and should not.** A class declares its fields and its methods in one body: data and behavior travel together, which is the entire point of reaching for a class. So an object-oriented model organizes **one file per aggregate** — `Order.dove` holds the `Order` class whole — with the value objects, enums, and errors it coordinates in a shared `types.dove` alongside it, since those are still records and enums.

```
orders-dovetail/src/
├── Order.dove        class Order — fields and behavior together
├── Shipment.dove     class Shipment
├── types.dove        value objects, state enums, errors, events
└── policy.dove       domain services
```

Be honest about what that costs. 19.1's real argument was not tidiness, it was that one readable file *is* the model — something to review, to walk through with a domain expert, to diff when the business changes. Split across aggregate files, the model stops being a single artifact and you get it back only by reading several files at once. The state enums and value objects still collect in `types.dove`, so a good deal survives; the aggregate shapes do not.

Do not try to recover the split with an extension or a module hanging off the class. Even where the language allows it, it is two patterns fighting: a class that has handed its behavior to somewhere else is a record wearing a class's syntax, and you would be better off with the functional style.

### Choosing

| | Functional (record) | Object-oriented (class) |
|---|---|---|
| Mutation | none — produce the next value | in place |
| Aliasing bugs | impossible | possible; a reference handed out can change |
| Updating | `self with { status = ... }` | `self.status = ...` |
| State *and* an event | returns a tuple | event only; state already changed |
| Event sourcing, audit, replay | natural | awkward |
| File layout | `types.dove` + a file per concept (19.1) | a file per aggregate; shape and behavior together |
| Fits Dovetail's `Result`-based, IO-free layer | closely | fine |
| Reads like the blue book | takes adjustment | yes |

**The recommendation: the functional style**, because it agrees with the rest of the language. Choose the object-oriented style if your team thinks natively in objects, or if you are porting an existing Java or C# model and want the shapes to line up. It is a coherent choice, not a lesser one. What you should not do is mix them.

---

## 19.6 Aggregates

An **aggregate** is a consistency boundary: a cluster of entities and value objects that must be correct *together*, with one entity — the **root** — as the only way in. `Order` is a root; `OrderLine` is inside its boundary and has no independent existence.

This is the most consequential modelling decision you make, because it decides what has to be correct together — and so what a unit of work looks like (20.1).

### The three rules

**1. Protect true invariants inside the boundary.** The test is temporal: if a rule must hold *at every instant*, everything it mentions belongs in one aggregate. If it may lag by a second without harm, it does not.

*"An order's total must equal the sum of its lines"* must never be observably false, so lines are inside `Order`. *"A customer's lifetime spend must reflect their orders"* can lag, so that is a handler (20.3), not an aggregate. And a *screen* that shows things together is not evidence of an invariant — that is a read model (20.2), and it can be assembled from anywhere.

**2. Reference other aggregates by identity.** An `Order` holds a `CustomerId`, never a `Customer`. Hold the object and three things follow: loading an order loads a customer which loads their orders; one aggregate's rules start reaching into another's state; and the boundary stops being visible in the code.

**3. No aggregate's invariants may depend on another's.** Each one has to be correct on its own, checkable from what it holds. If keeping A valid requires reading or changing B in the same breath, you have not found two aggregates — you have found one, drawn in the wrong place.

---

## 19.7 Domain Events

A **domain event** is a fact that has already happened, named in the past tense: `OrderPlaced`, `PaymentDeclined`. Not a command, not a request — a record of something that is now true.

```dovetail
public record OrderPlaced =
    orderId: OrderId
    customerId: CustomerId
    total: Money
    placedAt: Instant
```

### Return the event from the function that caused it

The temptation is an ambient event bus the aggregate can publish to. Resist it: publishing is IO, and this layer has none. The function that caused the fact returns it:

```dovetail
    public function place(
        self,
        now: Instant,
        creditApproved: Bool
    ): Result<(Order, OrderPlaced), OrderError> =
        match self.status with
            case OrderStatus.Draft =>
                if self.lines.isEmpty then
                    Error(OrderError.NoLines)
                else if !creditApproved then
                    Error(OrderError.CreditRefused)
                else
                    let total: Money = self.total()
                    let placement: Placement = Placement { placedAt = now; total = total }
                    let placed: Order = self with { status = OrderStatus.Placed(placement) }
                    let event: OrderPlaced = OrderPlaced {
                        orderId = self.id
                        customerId = self.customerId
                        total = total
                        placedAt = now
                    }
                    Ok((placed, event))
            case other => Error(OrderError.NotDraft(other))
```

The signature tells the whole story: *placing either fails for one of these reasons, or it succeeds, and here is both the order that resulted and the fact that is now true.* The caller decides what to do with the fact (20.5); the domain does not care whether it is published, logged, or dropped.

Two things in that body are worth calling out. The `Placement` is built once and stored *in the state*, so a placed order can never be missing its total — the invariant from 19.2 is maintained by construction rather than by a later check. And `now` is a parameter, not a clock reading, for the reason in 19.8.

This pair — **the new state and the event** — is the shape of every state-changing operation in the functional style. If an operation genuinely produces several events, return `Result<(Order, List<OrderEvent>), OrderError>`; the tuple already generalizes.

**The alternative** — carrying pending events on the aggregate and draining them in the application layer — handles multi-event operations more gracefully, at the cost of a field that is not really part of the aggregate's state and that someone must remember to drain. Prefer returning events.

### Domain events stop at the boundary

A domain event is phrased in domain types and **never leaves the context**. The application layer translates the ones that matter into *integration* events, phrased in contract types (18.9, 20.5, 21.5).

Conflating the two makes a model impossible to refactor: rename a field in your aggregate and you have broken a stranger's deployment. Keeping them separate costs one mapping function and buys the freedom to change your model whenever you understand it better — which is the entire point of having one.

Events carry value objects and IDs, never entities.

---

## 19.8 Domain Services

Some logic is genuinely about the domain but belongs to no single entity — because it spans two aggregates, because it is a policy about value types, or because the calculation is a concept in its own right. That is a **domain service**: a module of stateless functions in the domain package.

**A service is not a consolation prize.** The common advice is to suspect any service that reads only one aggregate, on the grounds that it is really a method with its receiver passed as an argument. Sometimes it is. Often it is not, and pricing is the archetype: a fee schedule has its own rules, changes on its own schedule, and may be swapped per tier, per contract, or per date. `Pricing.feeFor(order)` is not `Order.fee()` waiting to be discovered. An order is not the home of every rule that happens to read an order, and treating it as one is how an aggregate ends up owning half the model.

**The test is ownership, not argument shape.** Ask whether the rule is part of what the type *is*, or a policy applied to it. *"An order cannot be placed with no lines"* is the order's own business — it defines a valid order. *"This customer tier pays 1.5%"* is not; it is a policy that takes an order as input and would still make sense if the order type were replaced.

**The genuine failure is at the other extreme.** A domain layer that is all services and no methods is the anemic model (19.10) wearing a hat. If `Order` has no functions that can refuse, the rules that define an order have gone to live somewhere else.

### Pass the fact, not the port

Some rules need a fact the aggregate does not own. *"No two customers may share an email."* *"A customer may not have more than three open orders."* The aggregate cannot check either, and the obvious move is to hand it a repository so it can go and look.

Do not. **A domain function takes the answer to the question, never the means of asking it:**

```dovetail
    // Good: the fact is a parameter.
    public function place(self, now: Instant, creditApproved: Bool): Result<(Order, OrderPlaced), OrderError>

    // Bad: the domain now performs IO, and cannot be pure.
    public function place(self, credit: CreditService): Async<Result<OrderPlaced, OrderError>, ...>
```

The application service does the asking; the domain does the deciding. Three things follow:

- The domain stays **pure and total** — no `Async` in the layer, which is what makes the four-project layout of 18.5 possible.
- The test stays a one-liner. `order.place(noon(), false)` needs no fake credit service.
- The **cost becomes visible**. A lookup hidden inside a rule is a network call nobody budgeted for; a parameter forces the use case to fetch it deliberately, where a reader can see what it costs.

**The clock is the case you will hit first.** `Instant.now()` is IO, so `place` takes `now: Instant`. That reads like pedantry until the first time you test an expiry rule at an arbitrary date, or replay a day of events and get the right answers because time was an input rather than an ambient fact.

**On uniqueness specifically:** check-then-act races no matter which layer checks. Two requests can both find the email free. The guarantee is a unique constraint in the database; the domain-side check exists to produce a good error message in the common case. The domain layer is not where you solve concurrency, and pretending otherwise produces code that looks safe and is not.

---

## 19.9 Factories and Reconstitution

A **factory** is for construction complex enough to be its own concept, or where an invariant spans the whole assembly. In Dovetail that is a static function — `Order.draft`, `Money.of` — returning `Result` when it can refuse. There is no separate factory type unless the construction genuinely needs one.

### Reconstitution is a different operation

Creating an order and *rebuilding* one from a database row are not the same operation, though they end at the same type:

| | Creation | Reconstitution |
|---|---|---|
| Runs the creation rules | yes | **no** — they ran once, when it was created |
| Emits a creation event | yes | **no** — nothing happened |
| Assigns identity | yes | no — the identity is in the row |
| Valid starting states | `Draft` only | any state the order has reached |

`Order.draft` cannot rebuild a placed order — it hard-codes `OrderStatus.Draft`, and it should.

Modelling the states as an enum makes this notably easier: the adapter reads a status column plus its associated columns and builds the one `OrderStatus` variant they describe. If those columns disagree — a `placed` row with a null timestamp — the adapter has found corrupt data and must fail, which is exactly right and exactly where you want that check. In the `Option`-soup model of 19.2 that row would have loaded happily and failed somewhere else, much later.

Reconstitution needs a door of its own, since `Order.draft` is not it. Three options:

1. **A reconstitution constructor**, `public` and unmistakably named — `Order.fromStorage(...)`. Simple; the cost is a public door application code could also walk through, so naming carries the weight.
2. **A snapshot record** the aggregate exports and imports. The persistence-facing shape is explicit and the adapter's mapping is simpler; the cost is a second type to keep in step.
3. **Put the adapter's mapping inside `module Order`.** This grants construction access, but drags persistence vocabulary into the model. Moving the mapping to another function in the domain package does not grant private construction access.

Prefer (1), and (2) once the internal and stored shapes diverge. Whichever you choose, the function that actually reconstructs an `Order` lives in `module Order`. It must check the stored shape and invariants without repeating command preconditions or emitting a new creation event. A snapshot is data, not construction permission: decode the snapshot, then pass it to that module function. A generated decoder cannot bypass private construction either.

---

## 19.10 The Anemic Domain Model

The failure mode worth naming, because it is where most codebases end up without a fight:

- Entities are records of public fields with no behavior.
- All behavior lives in services that take those records as arguments.
- The domain layer is a namespace for data structures, and the rules are in the application layer — or in three places at once.

It happens because it is what ORMs teach, what DTO-mapping habits encourage, and what CRUD screens make look reasonable. It is not stupid; it is the path of least resistance.

**How to spot it in review:**

- Application services full of `if` statements about the business.
- Entities with setters and no function that can refuse.
- The same validation in the HTTP handler, the service, and the database.
- **A record whose fields are mostly `Option`** — the tell from 19.2, and usually the earliest one. Optional fields are states that were never modelled, and the rules keeping them consistent had to go somewhere else.
- **A model written in `String` and `Int32`** — the tell from 19.3. Rules attach to types; a layer with no types of its own has nowhere to put them.
- A rule you cannot point at.

**Why it costs:** the rules are still in your program, but duplicated, with no copy authoritative. Every change means finding all of them, and the compiler cannot help, because a missing rule is not a type error.

**The fix is directional, not a rewrite.** Each time you touch a rule, move it onto the type that owns the data it reads, and delete the other copies. Where the rule is really about which combinations are legal, fix the type instead and the rule disappears. A codebase converges surprisingly fast under that habit, and it is safe at every step — which a big-bang re-model is not.

---

## 19.11 Testing the Domain

Domain tests are the ones to have thousands of: they test the thing that matters and cost nothing to run — no database, no runtime, no `Async`, no fakes.

**Write them in the module, not in `test/`.** Domain tests belong at the bottom of `Order.dove`, under the functions they pin. 15.2 draws the line by what a test is for: `test/` is for exercising a package's public API from the outside, `src/` is for tests that are part of the code. A rule and the test that holds it in place are one thought, and they should be one edit — when a rule changes, its test is on the screen; when a rule is deleted, so is its test, rather than being found six months later in a file nobody opened.

The practical difference is the top of the file. In `test/` the example below would open with `package test` and eleven `import` lines, every one of them a thing to update when the model moves. In `Order.dove` there are none: the aggregate, its states, and its errors are already in scope, and `Money` and `Sku` are already imported for the production code above. Private helpers are reachable too, which `test/` cannot do.

```dovetail
// the tail of Order.dove, after module Order

private function anOrder(): Order =
    Order.draft(OrderId.parse("o-1").require, CustomerId.parse("c-1").require)

private function aLine(): OrderLine =
    OrderLine {
        sku = Sku.parse("ABCD1234").require
        quantity = Quantity.parse(2).require
        unitPrice = Money.of(1250i64, Currency.Usd)
    }

private function noon(): Instant = Instant.ofEpochSecond(1700000000i64)

test "an order with no lines cannot be placed" =
    assert anOrder().place(noon(), true).isError

test "a placed order carries when it was placed and what it came to" =
    let drafted: Order = anOrder().addLine(aLine()).require
    match drafted.place(noon(), true) with
        case Ok((placed, event)) =>
            match placed.status with
                case OrderStatus.Placed { total; placedAt } =>
                    assert total.minorUnits == 2500i64
                    assert placedAt == noon()
                case _ => panic "expected a placed order"
            assert event.total.minorUnits == 2500i64
        case Error(_) => panic "expected the order to place"

test "the draft is unchanged by placing it" =
    let drafted: Order = anOrder().addLine(aLine()).require
    drafted.place(noon(), true)
    assert drafted.placedAt().isNone

test "placing twice reports what the order actually was" =
    let drafted: Order = anOrder().addLine(aLine()).require
    let (placed, _e) = drafted.place(noon(), true).require
    match placed.place(noon(), true) with
        case Error(OrderError.NotDraft(OrderStatus.Placed(_))) => assert true
        case _ => panic "expected NotDraft carrying the real status"
```

Things worth copying:

- **A couple of small builders** (`anOrder`, `aLine`, `noon`) keep the tests about the rule rather than the setup. They are file-private functions, so they never leak into the package's surface. Tests after an inline module are still file-level declarations: being in `Order.dove` does not grant private construction access. `anOrder` correctly calls `Order.draft`.
- **Notice what you are not testing.** There is no test that a draft has no `placedAt`, or that a placed order has a total — those are not true because of a check, they are true because of a type, and a test would only be re-stating the type. **The better your types, the fewer tests you need**, and the ones left are about behavior rather than about data hygiene.
- **The third test cannot be written in a mutable model.** `place` is called, its result discarded, and the draft is still a draft.
- **Match the specific error, including its payload.** The fourth test asserts not just "this refused" but that the refusal carried the real status — which is the thing 19.2 added, so it is the thing worth pinning.
- **A controlled clock is free** because `now` is a parameter (19.8).

Test rules, not plumbing: `Order.draft` needs no test, and neither does an accessor.

**What does belong in `test/`** is the layer above: a use case exercised through its public surface, with the repository faked (20.8). That is a test of the package from outside, which is exactly what the directory is for.

---

## 19.12 A Change, End to End

The reason for all of this is what happens when the business changes its mind. Suppose orders above 1,000.00 now need approval.

The rule concerns data the aggregate already has, so it goes in `place` — and the error carries the total that tripped it, so the caller need not re-derive it:

```dovetail
                    let total: Money = self.total()
                    if total.isGreaterThan(Money.of(100000i64, total.currency)) then
                        Error(OrderError.ApprovalRequired(total))
                    else
                        ...
```

One new error variant in `types.dove`, four lines in `Order.dove`, one new test. The application service, HTTP handler, repository, and database are untouched — and every caller that matches exhaustively on `OrderError` now gets a compile error telling them there is a new outcome to handle.

Now a harder change, and a more instructive one: *"an approved order records who approved it."* That is not a new check, it is a **new state**, so it belongs in the type:

```dovetail
public record Approval =
    approvedBy: UserId
    approvedAt: Instant

public enum OrderStatus =
    Draft
    AwaitingApproval(Money)
    Approved(Approval)
    Placed(Placement)
    Cancelled(Cancellation)
```

Adding that variant breaks every exhaustive match in the domain layer, and each break is a real question: can you add a line to an order awaiting approval? Can you cancel one? The compiler has just produced the design review, and you cannot ship until you have answered all of it. Compare that with adding an `approvedBy: Option<UserId>` field, which compiles immediately and answers nothing.

And when a rule genuinely needs a fact the aggregate does not have — *"the approver must not be the buyer"* — it becomes a parameter, and the use case must supply it:

```dovetail
    public function approve(self, now: Instant, approver: UserId): Result<(Order, OrderApproved), OrderError>
```

so the application layer changes too. That is the design telling you the truth: a new input is a new cost, and it shows up at the layer that pays for it.

---

## Summary

- **Start with the types.** One `types.dove` you can read in one sitting is the model; behavior goes in a file per concept. Design the shapes before the functions.
- **Make illegal states unrepresentable.** Put data inside the state that gives it meaning, so a `Draft` has no `placedAt` and a `Placed` order cannot lack a total. Parallel `Option` fields next to a status enum is the anti-pattern to recognize.
- **`Option` means optional in every state**, not filled in later. Errors carry their own evidence. A `case _ =>` in the domain layer forfeits the compile errors that would have found you.
- **Value objects** by default — a bare `String` or `Int32` in the model is a smell, because the rule about it usually arrives later and needs somewhere to live. Private newtype construction through its module so holding one proves it is valid, living at the innermost place that needs it.
- **Entities** have identity; IDs and clocks are supplied from outside. Private record construction and `with` updates make the associated module own their transitions, while callers can still inspect them.
- **Pick one style for the whole layer.** The functional style is recommended — it agrees with Dovetail's `Result`-based, IO-free layer.
- **Aggregates** are consistency boundaries, drawn by invariants. They reference each other by ID, and none of them depends on another's invariants.
- **Domain events are facts**, returned from the function that caused them, stopping at the context boundary.
- **Pass the fact, not the port** — including the clock.
- Every `Result` in a domain signature is a rule a type could not carry. That is often fine, and it is always worth noticing.

Part 20 puts this model to work: use cases, transactions, the repository ports that load and save aggregates, and the three kinds of trigger that drive them.


---

# Part 20: The Application Layer

Source: https://dovetaillang.org/book/application-layer/


> **Status: outline.** Bullets to be expanded into prose. Part 19 built the model;
> this part is about the layer that drives it — the use cases, and the three kinds
> of thing that trigger them. Part 21 zooms out to other contexts.

---

## 20.1 What a Use Case Owns

- A use case takes **one intent** — place this order, close this card — and owns **everything that intent entails**. That is a larger job than the usual formula admits, because only some of what an intent entails is a write to your own database.
- **The shape, from 18.3: load, decide, persist, announce.** The decision is a domain call and is one line; everything around it is plumbing.
- **It holds no business rules.** The review test: an `if` in an application service is either a guard (fine), a mapping (fine), or a business rule (a bug — it belongs on the aggregate).
- **The transaction is a tool, not the definition.** Where a consequence can be made atomic with the decision, make it atomic. Where it cannot — an HTTP call, another context, a broker — it does not stop being yours, and 20.6 is how you discharge it.
- The application layer is where the **unit of work** begins and ends. Who owns the transaction — the repository, an explicit `Transaction` port, or the adapter — and why the domain must not know about it.
- **The only IO inside a database transaction is database IO.** No HTTP calls, no queue publishes, no calls into another bounded context. Two independent reasons, and both bite in production:
  - **Transactions get retried.** At repeatable-read or serializable isolation, serialization failures are routine rather than exceptional, and the documented correct response is to retry the whole transaction. Every external call inside it is then re-issued — once per attempt.
  - **A commit can fail after the call succeeded**, and you cannot un-send an HTTP request. The card is closed at the network and open in your database.
  - This is the sandwich again, stated for storage: the transaction is part of the bottom slice, and it writes to exactly one place.

### The "one change, one transaction, one aggregate" rules

You will meet these everywhere, usually stated as laws:

> One use case, one transaction. One transaction, one aggregate. One change at a time.

As **aspirations** they are sound: they push you to notice coupling and to ask whether two things really are separate. As **laws** they are wrong, and each one fails on the first example anybody reaches for.

**"One transaction, one aggregate"** fails on a transfer between two accounts. It touches two `Account` aggregates *and* writes a `JournalEntry` — its own aggregate, because an account cannot carry its entire history — and all three must land together or none of them. Turning that into a saga, with compensating actions and an intermediate state where the money is in neither account, is a great deal of machinery to avoid a database transaction that would have done it correctly. **Atomicity is a storage decision, not a modelling one.** Write as many aggregates in one transaction as correctness requires and your store can give you. What 19.6's third rule forbids is stricter and different: not "two aggregates in one transaction", but "two aggregates that cannot be reasoned about separately".

**"One change"** fails because a single intent routinely has several consequences, and only some of them are writes you control. Closing a card updates a row, tells the card network, notifies the customer, and may release a spending limit held in another context. Insisting that the use case does one thing does not make the other three disappear — it means nobody has written down whose job they are.

What survives is the pair of questions underneath: *does this really have to be atomic?* and *is this second thing genuinely mine?* Both deserve an honest answer, and sometimes the honest answer is yes.

### Consequences: notification or obligation

When an intent has a consequence that cannot be in the transaction, there are two genuinely different situations. Conflating them is where systems quietly go wrong.

**A notification.** *"This happened; react if it concerns you."* The consequence belongs to whoever is listening. Publish an integration event (20.5) and you are finished: if a subscriber fails, that is the subscriber's problem to retry, and your use case was correct the moment it committed.

**An obligation.** *"This must also happen, and it is my job to see that it does."* Closing a card at the card network is not a courtesy extended to a listener — the card is not closed until the network says so. If nothing ever makes that call, your context is **wrong**, not merely unobserved.

The test is one question: **if this never happens, whose bug is it?** If it is yours, it is an obligation, and publishing an event does not discharge it. It only makes the failure harder to see, because the outstanding work is now invisible in a broker instead of pending in your own state, where you could have found it.

This is worth being deliberate about, because the prevailing fashion pushes everything toward notification — it makes each service look simple in isolation. The cost arrives later and lands somewhere else: causality becomes something you reconstruct from logs, and a step nobody owns is a step nobody is paged for. **When a consequence is an obligation, keep it.** 20.6 is how you make one you own survive a crash.

### The sandwich: IO at the edges

That shape has a name — **impure, pure, impure** — and it is the target for every use case in the layer:

```
    load       impure   queries, the clock, a call to another context
    decide      pure    the domain layer (Part 19)
    save       impure   persist, publish, commit
```

- **Only the middle has business rules**, and it needs no adapters to test — it is the domain layer, so 19.11's tests already cover it.
- **The edges have nothing worth testing.** They fetch and they write. No branching, no rules.
- **This is what makes "pass the fact, not the port" (19.8) practical.** The top slice is where facts get gathered, so the domain never needs a port to go looking. The two ideas are the same idea from different ends: the domain refuses to do IO, and the sandwich is the shape that lets it.
- **The transaction wraps the bottom slice** — or the whole thing, if a read has to be consistent with the write.

A use case that reads as one sandwich is almost certainly right. When one does not, that is information.

### When the sandwich does not fit: the layered cake

Sometimes you cannot gather everything up front, because **what to load depends on what the model decided**. Placing an order picks a fulfilment centre; only then do you know whose stock to check. Pricing picks a tax regime; only then do you know which rate table to read.

```
    load       impure
    decide      pure
    load       impure   ← could not have known to fetch this any earlier
    decide      pure
    save       impure
```

That is a **layered cake**, and it is normal — not a design failure, and not something to contort the model to avoid. What matters is that the layers stay honest:

- **Each pure slice stays pure.** No port sneaks into the domain because there are now two calls instead of one. 19.8 does not relax.
- **Each impure slice stays dumb.** It fetches what it was told to fetch. If choosing *what* to fetch involves an `if` about the business, that `if` is a rule and belongs in the slice above it.

Three ways to keep the cake thin, in order of preference:

1. **Over-fetch and stay a sandwich.** Load everything the use case might need up front. Costs a sometimes-wasted query; buys a shape anyone can read at a glance. For a two-branch case this is usually the right trade, and people reach for it far too rarely.
2. **Accept two layers.** Entirely fine. Name the intermediate value after the decision that produced it — `chosenWarehouse`, not `data2` — so the alternation stays legible.
3. **Let the model ask.** The domain function returns what it needs as a **value** — an enum of required facts — and the application fetches it and re-enters. The branching stays in the domain where it can be tested purely; the application becomes a small loop that services requests. Costs a protocol, buys the purity back.

**The warning sign is height.** A five-layer cake means the *sequence itself* has become business logic, and it now lives in the application layer — where it cannot be unit-tested without adapters and cannot be pointed at (19.1). That is the moment for (3), or for asking whether this use case is really a saga (20.6).

**And note what every layer above quietly assumes: that the process survives to the end.** Sandwich and cake alike are shapes for a single run. If the machine dies between two impure slices, everything after the last commit simply did not happen — and if the model already decided something that the outside world was told about, or was about to be told about, you are now inconsistent with it. That is a different problem, it has its own name, and it is 20.6.

## 20.2 Commands, Queries, and Results

- **Commands are types, not parameter lists.** `PlaceOrder` as a record beats six positional arguments: named, validated, loggable, and replayable.
- Where the command type lives: `application`, built by the driving adapter from a contract DTO. The DTO is the wire; the command is the intent. They diverge sooner than you expect.
- **Validation happens twice, and that is correct.** The adapter checks shape ("is this valid JSON with a non-empty id"); the dovetail checks rules ("can this order be placed"). Neither can do the other's job.
- **Never return an aggregate from a use case.** Return the ID, or a small result type. An aggregate handed to a caller is an aggregate mutated outside a transaction.
- **Queries are not use cases.** Read models bypass the domain and return contract types (18.6). Do not route a screen through an aggregate.
- **Error mapping is a three-hop chain,** and each hop belongs to a different layer:
  - domain error (`OrderError.NotDraft`) — the rule that refused
  - application error (`PlaceOrderError.Rejected`) — plus the failures only the use case can have: not found, storage, upstream
  - contract error (`OrderServiceError`) — wire-stable, what a caller can act on
  - Collapsing these is tempting and costs you the ability to change any of the three independently.

### Errors from the domain

The first hop is the one you write dozens of times, so it is worth having an idiom for.

An aggregate refuses with `Result<T, OrderError>`. A use case returns `Async<T, PlaceOrderError>`. Those error types are deliberately different, because **the use case can fail in ways the domain cannot**: the order was not found, the database was unreachable, another context said no. The application error is the wider type, and the usual shape is an enum that wraps the domain's and adds its own:

```dovetail
public enum PlaceOrderError =
    Rejected(OrderError)      // the model said no
    NotFound
    Storage(RepositoryError)
    Upstream(LookupError)
```

`Rejected(OrderError)` rather than a flattened copy of the domain's variants: the domain owns that list, it will grow (19.12), and copying it means editing two enums forever.

**Write the conversion once, as a `From` implementation:**

```dovetail
implement From<OrderError> for PlaceOrderError =
    public function from(value: OrderError): PlaceOrderError =
        PlaceOrderError.Rejected(value)
```

**Then use it as a method reference at the call site:**

```dovetail
async function handle(self, command: PlaceOrder): Async<OrderId, PlaceOrderError> =
    let order: Order = ...
    let (placed, event) = order.place(now, creditApproved)
        .mapError(PlaceOrderError.from)
        .orReturn
    ...
```

`.mapError(PlaceOrderError.from).orReturn` is the idiom. It reads as one hop, the conversion lives in exactly one place, and adding a variant to `OrderError` does not touch any call site.

**Where the conversion is automatic, and where it is not.** This is worth knowing precisely, because the two look similar and behave differently:

- **At a `use` site**, the compiler inserts the conversion for you. `use fileResource` inside a function returning `Async<_, AppError>` works when `From<FileError> for AppError` exists — no `.mapError` at all (Part 13).
- **At a `try`/`orReturn` site**, it does not. The lift that exists in the standard library carries the error type through unchanged (`Result<T, E>` into `Async<T, E>`), so `orReturn` only works directly when the two error types already agree. Crossing from `OrderError` to `PlaceOrderError` needs the explicit `.mapError`.

That asymmetry is a wrinkle in the language rather than a rule with a reason behind it — but it is what compiles today, so write the `.mapError`. The `From` implementation is still worth defining: it is what makes `use` sites clean, and it gives the explicit hop a name instead of an inline lambda repeated at twenty call sites.

**The third hop happens at the driving adapter** (18.3), not here. The use case returns `PlaceOrderError`; the HTTP handler turns it into a status code and a contract error. That keeps wire compatibility a concern of the layer that owns the wire.


## 20.3 The Three Triggers

- A request, an event, and a clock. **Same shape, different door** — which is the point of the layer: one use case, reachable three ways.

### Requests

- Driving adapters (18.3) decode, build a command, call the service, encode the result. No logic in between.

### Event handlers

- **Two kinds, and they are not the same pattern:**
  - **Internal** — a domain event from this context (19.7) drives a second aggregate. Reach for this when the second change may genuinely lag — not to avoid writing two aggregates in one transaction (20.1), but because they are not required to be correct at the same instant.
  - **External** — an integration event from another context, translated at the subscriber into *your* command before it reaches the handler (Part 21.5). The handler never sees a foreign type.
- **Idempotency is the handler's defining constraint.** At-least-once delivery is the norm, so a handler must be safe to run twice. Where the dedup lives — the adapter, a processed-events table, or a naturally idempotent operation — and why "naturally idempotent" is the one worth designing for.
- Failure handling: retry, dead-letter, and the fact that a handler cannot signal failure back to the publisher.

### Jobs

- Scheduled or periodic work: expiry sweeps, reconciliation, reminders, retries of an outbox.
- **The clock is a port.** A job that reads the wall clock directly is untestable; inject it and time becomes a value you control.
- **Commit per item, not per batch.** Iterate and commit each item's work as it goes, rather than widening one transaction over the whole sweep. Consequences: partial progress, resumability, and why that is better than a batch that half-fails.
- A job is a use case with a timer for a caller — so it holds no more logic than one, and should usually call the same application service a request would.

## 20.4 Repositories

- **Why the port lives here and not in the domain layer.** Evans places the repository interface in the domain layer; Part 18 places it in `application`. That is forced by a language fact, and the result is the more honest boundary:
  - A repository signature returns `Async`. `Async` is an IO concept, and the domain layer has none — in the four-project layout (18.5) putting it there is a compile error, not a style debate.
  - Evans' placement is a consequence of Java and C# being unable to say "returns a value" versus "performs an effect" in a type. There was no seam there to land on. Dovetail has one, so the split falls where the effects actually change.
  - What stays in `domain` is what is genuinely domain: the aggregate, its invariants, its events (Part 19). What lives here is a *persistence* concept expressed in domain terms. The aggregate does not know it is stored, and now it cannot pretend otherwise.
- **One repository per aggregate root** (19.6). No repository for a part of an aggregate — that is a hole in the boundary.
- Repositories are a *collection* illusion: `findById`, `save`, and a small number of domain-meaningful finders. Not a query language.
- **Methods speak aggregates**, never rows and never DTOs. A method returning `OrderSummaryDto` is a query service, not a repository — give it its own port (18.6, 20.2).
- **Reconstitution.** The adapter must rebuild an aggregate without re-running its creation rules; the options and their costs are in 19.9. The choice is the adapter's to consume but the domain's to offer.
- **The `version` check on save** is where optimistic concurrency actually happens — a storage concern the domain layer knows nothing about. A save that finds a changed version fails the use case, and the caller retries the whole thing — not the write.

## 20.5 Publishing Integration Events

- The application layer decides which domain events become integration events (19.7) and publishes them through a port; infrastructure delivers them. (The *consumer's* side of the same wire — translate or conform — is 21.5.)
- **The dual-write problem:** you cannot atomically commit the database and publish to a broker. Say this plainly rather than letting readers discover it in production.
- **The transactional outbox** as the standard answer: write the event to the same database, in the same transaction; a relay publishes it after. Where each piece lives in the layout of Part 18.
- Translation direction: domain event → integration event is a *narrowing*, chosen deliberately. Not everything the model notices is anyone else's business.

## 20.6 Sagas, Compensation, and Durable Execution

For work that spans several aggregates, several contexts, or a long stretch of time — where one transaction is impossible and a distributed one would be worse.

### Two shapes, and the word only covers one of them

The [1987 Sagas paper](https://www.cs.cornell.edu/andru/cs711/2002fa/reading/sagas.pdf) describes two recovery strategies. In current usage "saga" almost always means the first, which is a shame, because the second is the one most systems actually need.

- **Backward recovery.** Each step has a **compensating action**; on failure you unwind. Compensation is a business decision — refund, cancel, apologise — not a rollback, which is exactly why no framework can generate one for you.
- **Forward recovery.** The workflow is checkpointed and driven relentlessly to completion. On interruption it resumes from the last **save point** rather than unwinding. Today this generally goes by the name **durable execution**.

Which you need is a question about the work, not about taste. **If a step cannot be undone — money moved, an email sent, a card closed at the card network — forward recovery is the only honest answer**, because there is no compensation to write.

### The problem durable execution solves

This is the failure you will actually hit, and 20.1 has already ruled out the easy way round it.

The model decides something, you commit it, and now you must tell an external service or another bounded context:

- Put the external call **inside** the transaction and a retry re-issues it — and serialization retries are routine (20.1, 20.4). Retry the transaction a hundred times and you have closed the card a hundred times.
- Put it **after** the commit, which 20.1 says you must, and a crash in the gap leaves your database saying *closed* and the other system saying *open*.

There is no arrangement of one process and one transaction that removes this. **The commit and the call cannot be made atomic**, so the only remaining move is to make the pair *recoverable*: record that the call still has to happen, durably, in the same transaction as the decision — and then make sure something eventually performs it.

### What a durable runtime gives you, and what it demands back

- **Save points** after each step, and resumption from the last one.
- Because a crash can land between "the step finished" and "the save point was written", steps are **at-least-once**. So **every step must be idempotent** — the same requirement an event handler owes you (20.3), generalized to the whole workflow. For an external call that usually means an idempotency key the far side honours.
- **Deterministic replay.** Any value the workflow generates — a UUID, a timestamp, a random choice — must be generated once and persisted, so a resumed run sees the same value. This is what makes an idempotency key survive a restart: a freshly generated key on the second attempt is not an idempotency key at all, it is a second request.

**Part 19 already did the hardest part of this.** Aggregates that take `now` and their identifiers as parameters rather than reading a clock or a generator (19.4, 19.8) are replayable by construction: feed the same inputs and you get the same decision. A domain layer that read the clock itself could not be replayed deterministically at all. Whatever you build on top, that discipline is the prerequisite — and it is one more reason the rule was worth insisting on.

### Dovetail has no durable execution runtime today

Say this plainly rather than implying otherwise: there is no `Saga` type, no save-point store, no workflow coordinator in the language or its standard library. What you do in the meantime, cheapest first:

1. **Reach for the outbox (20.5) first.** It *is* durable execution, for exactly one step: the publish. If the only thing that must follow the commit is "tell someone", the outbox is the entire answer and you need none of the machinery below. This covers far more cases than people expect, because "call the other context" can usually be turned into "publish a fact and let them react".
2. **For a genuine multi-step workflow, hand-roll forward recovery.** Persist the workflow's state as its own aggregate, advance it one step per transaction, and drive it with a job (20.3) that picks up unfinished work. Generate idempotency keys **at the moment the workflow state is written**, not at the moment of the call, so a resumed run reuses them. This is well-trodden and a few hundred lines; it is not research.
3. **Or delegate to an external coordinator** — Temporal, Restate, and similar — with your Dovetail services as the workers. You buy save points, retries, and visibility, and you pay in an extra piece of infrastructure and a programming model that wants to own your control flow.

This is the honest extension of the layered cake (20.1): the cake alternates pure and impure slices within one run, and durable execution is what you need when the run itself may not survive to the end.

*(An aside, not a plan: `Async` in Dovetail is a reified tree of effects rather than an opaque continuation, which happens to be the shape a checkpointing runtime needs. Whether that ever becomes durable execution in the language is an open question.)*

### Structuring one, whichever recovery you use

- Where it lives: `application`, since it orchestrates rather than decides. Its persisted state is its own aggregate — a workflow has an identity and a lifecycle like anything else, and 19.2 applies to its states as much as to an order's.
- **Choreography vs orchestration.** Choreography (each context reacts to events) is loosely coupled and very hard to see; orchestration (one coordinator drives) is visible and centralizing. Prefer orchestration past about three steps, purely because you can debug it.
- **Timeouts are first-class.** Most saga bugs are the branch nobody wrote for "the reply never came."

## 20.7 Cross-Cutting Concerns

- **Authorization belongs here.** The use case is the permission unit — "may this actor place this order" — not the entity and not the HTTP route. The actor arrives as part of the command, not from an ambient context.
- **Logging and tracing** wrap the use case; the domain layer stays silent. A span per use case is the natural granularity.
- **Retries and timeouts** belong to the adapter, not the service. A use case that retries is a use case whose transaction boundary is unclear.
- The general rule: if a concern is about *how the program runs* rather than *what the business decided*, it wraps the use case rather than living inside it.

## 20.8 Testing the Application Layer

- In-memory adapters, not mocks: ports are [interfaces](https://dovetaillang.org/book/type-system.md#611-interfaces-and-interface-types), so a fake repository backed by a `List` is a few lines (18.10, 20.4).
- What these tests assert is **orchestration**, not rules: was the aggregate saved, was the event published, was the right error returned. The rule itself is already covered by a dovetail test.
- **Test the handler's idempotency explicitly** — deliver the same event twice and assert the second is a no-op. This is the bug that reaches production otherwise.
- A controlled clock makes job tests deterministic and fast.

## 20.9 Worked Example

- Continue Part 19's `Order`: the `PlaceOrder` use case end to end, then the same aggregate driven by an event handler and by an expiry job — showing the three triggers over one unchanged domain model.
- Then a saga: place order → reserve stock → take payment, with compensation on each failure branch.

---

## Summary (to write)

- A use case owns **one intent and all of its consequences**, and holds no business rules. "One change, one transaction, one aggregate" are useful questions and bad laws.
- A consequence outside the transaction is a **notification** (someone else's to react to) or an **obligation** (yours to complete). If its never happening is your bug, an event does not discharge it.
- Commands are types; aggregates never leave the layer; errors are mapped in three hops.
- **Use cases are sandwiches:** IO at the edges, decisions in the pure middle. That shape is the other half of "pass the fact, not the port".
- When you cannot gather everything up front, a **layered cake** is honest — but height is a warning that the sequence has become a business rule.
- Requests, events, and jobs are three doors to the same use case — handlers additionally owe you idempotency.
- Dual writes are a real problem with a boring solution: the outbox.
- Sagas coordinate what a transaction cannot. **Backward recovery** compensates and unwinds; **forward recovery** (durable execution) checkpoints and completes — and it is the only option once a step cannot be undone.
- Dovetail has **no durable execution runtime today**. The outbox covers the one-step case; beyond that you hand-roll forward recovery or delegate to a coordinator. Part 19's rule that clocks and IDs are parameters is what makes any of it replayable.


---

# Part 21: Strategic Design and Context Mapping

Source: https://dovetaillang.org/book/context-mapping/


> **Status: outline.** Bullets to be expanded into prose. Part 18 gave one context its shape,
> Part 19 filled it and Part 20 drove it; this part is about the space *between* contexts —
> which relationships exist, and what each one costs.

---

## 21.1 Subdomains: Core, Supporting, Generic

- **Core** — the reason the business wins. Model it carefully; spend your best effort here.
- **Supporting** — necessary, specific to you, not a differentiator. Model it adequately.
- **Generic** — solved the same way everywhere (auth, notifications, tax tables, geocoding). Buy it, or wrap something.
- This classification is not academic: **it is the single best predictor of how much translation to buy at a boundary** (21.4). Effort follows value.
- A context is not the same thing as a subdomain: a subdomain is a slice of the *problem*, a bounded context is a slice of the *solution*. Aim for one-to-one; accept that legacy rarely is.

## 21.2 Ubiquitous Language and Bounded Contexts

- A bounded context is the scope within which one language is consistent. Outside it, the same word means something else — and that is fine.
- The canonical example, worth using because it is unavoidable in practice: "customer" to Orders is a shipping address and a credit status; to Billing it is a tax jurisdiction and a payment instrument.
- **The language should be readable in the code.** In Dovetail, that means package names, type names, and method names all come from the business vocabulary of that context, and `primitives` is where the shared nouns get their types.
- Finding boundaries: follow the language, the data that changes together, and the teams. Where a term needs a qualifier to stay unambiguous ("billing customer"), you have found a seam.

## 21.3 Context Relationship Patterns

Evans' catalogue, each mapped onto Dovetail's project mechanics:

| Pattern | Leverage over upstream | Communication | In Dovetail |
|---|---|---|---|
| Shared Kernel | joint ownership | shared types, no translation | the `shared-kernel` project (18.8) |
| Partnership | mutual, coordinated releases | direct, both directions | mutual `depends` on each other's `contract` |
| Customer/Supplier | your needs are in their backlog | direct, or a thin ACL | `depends` on their `contract` + a mapping module |
| Conformist | none, but their model fits | direct contract use | `application` imports their contract types |
| Anticorruption Layer | none, or their model does not fit | translated | port in `application`, stub + translator in `infrastructure` |
| Open Host Service | you are one of many consumers | a published, general-purpose surface | the `contract` project's service interfaces |
| Published Language | — | a documented interchange vocabulary | the `contract` project's DTOs and events |
| Separate Ways | — | none | no `depends` edge at all |
| Big Ball of Mud | — | ACL, always | isolate behind one port; do not extend the model into it |

- **The `contract` project is Open Host Service and Published Language made into a build artifact.** The service interfaces are the OHS; the DTOs and integration events are the Published Language. Worth stating plainly — it is why Part 18's structure works.
- Partnership and Shared Kernel are the two that create *coupling between teams*, not just between codebases. They should be rare and deliberate.
- Separate Ways is a real answer. Duplicating a small capability often beats an integration nobody owns.

## 21.4 Direct Contract Use vs Anticorruption Layer

- The choice is a spectrum, not a binary. The chapter's job is to say where the line sits.
- **Conformist is right when:** the concept is in a *generic* or *supporting* subdomain; the consumed surface is small and read-only; upstream is a genuine Published Language; or you release together anyway.
- **ACL is right when:** the concept is in your **core domain** — the decisive criterion, because a foreign shape distorts the model you are paid to get right. Also: upstream is legacy or third-party, you have no release leverage, you may swap providers, or their model is far bigger than your need.
- **Costs, stated honestly.** ACL: a duplicated type, a mapping function, mapping tests, one more hop when debugging. Conformist: their vocabulary spreads through your code, their breaking change is your migration, their release schedule is yours.
- **The recommendation:** default to a *thin* ACL even when the mapping is nearly 1:1. Its value is not clever translation — it is that there is exactly one place to change when upstream renames a field. Choose Conformist where you genuinely do not care about the concept.
- **Consumer-driven contracts** as the middle path: the downstream declares what it needs and tests against the upstream, turning an accidental Conformist relationship into an explicit Customer/Supplier one.
- **Reading your real context map off `Dovetail.toml`** — the Domain-specific payoff:
  - `acme.orders.application` imports `acme.customers.contract.*` → you are a **Conformist**, whether you meant to be or not.
  - Only `acme.orders.infrastructure` imports it → you have an **ACL**.
  - One grep tells you which relationship you actually have, versus the one on the whiteboard.
  - It can be made structural: promote `infrastructure` to its own project and it becomes the only project that depends on foreign contracts — Conformist-by-accident is then a compile error. Cost: one more manifest entry (the 18.5 trade-off applied to a different wall).

## 21.5 Integration Events

- **Scope split with Part 20.** Publishing is 20.4 (which events to raise, the dual-write problem, the outbox); handler mechanics are 20.3 (idempotency, retries, dead-lettering). This section is about the *consumer's* strategic choice: whether a foreign event reaches your model as-is or translated, and what the schema contract between contexts has to guarantee.
- The instinct is to consume events as-is because each one looks small. **Argue the other way** — the case for translation is *stronger* for events than for RPC:
  1. **Zero say over granularity.** With RPC you at least choose which call to make; with events you get whatever they publish, at whatever grain they chose.
  2. **Already translated once — for the publisher.** Their domain event → their integration event was optimized for their model, not for any consumer.
  3. **The ACL is nearly free.** Events land in a subscriber adapter you had to write anyway; the translation is a function in code that already exists.
- **The recommendation:** translate at the subscriber into your own command or your own event type, before it reaches the application layer. Handlers take `MarkBuyerDelinquent`, not `CustomerDelinquencyChanged`. Then schema versions stay in the subscriber, two upstream events can collapse into one internal command, and handler tests need no foreign schema.
- **Consume as-is when** the event is a bare fact (`OrderCancelled { orderId }`) where translation is the identity function, or when you own both sides.
- **Notification vs event-carried state transfer.** A notification carries an ID and you call back for detail: low coupling, extra round trip. ECST carries the full payload: fast, works when upstream is down — but it bakes the upstream's shape into *your database*, which makes the ACL more important, not less, because the foreign shape is now durable.
- **Delivery concerns belong in the adapter** (mechanics in 20.3). The strategic point here: if an application handler contains "have I seen this ID before", a concern has leaked inward — and it leaked across a context boundary, which is worse.
- **Event schema evolution is stricter than RPC evolution.** No negotiation, and old events live in a log forever. Additive-only; version in the type name when you must break.
- **The subscription is still a compile-time dependency.** Even though the runtime arrow points from producer to consumer, the consumer `depends` on the producer's `contract`, and that edge counts in the workspace DAG.

## 21.6 Drawing and Maintaining the Context Map

- A context map is a picture of relationships, not of components. Each edge is labelled with a pattern from 21.3 and a direction (upstream/downstream).
- Keep it honest: the map is a claim about your code, and in Dovetail the code can be checked against it (21.4).
- When the map has an edge nobody can name, that is the finding.

## 21.7 Splitting and Merging Contexts

- **Splitting:** what Part 18's structure makes cheap — the consumer already depends only on a `contract`, so extracting a context is a deployment change plus a transport swap in one adapter.
- **Merging:** when two contexts have the same language, the same team, and always release together, the boundary is costing more than it returns.
- Migration shapes worth sketching: strangler-style extraction behind an ACL, and event-driven backfill.

---

## Summary (to write)

- Classify subdomains first — core/supporting/generic decides how much boundary discipline is worth buying.
- The `contract` project is your Open Host Service and Published Language; the ACL is how you consume someone else's.
- Default to a thin ACL, especially for anything touching the core domain, and especially for integration events.
- The relationship you actually have is visible in `Dovetail.toml` and in which package imports the foreign contract.


---

# Part 22: Standard Library Overview

Source: https://dovetaillang.org/book/stdlib/


The compiler bundles `standard.prelude`. Other libraries are projects selected in
`Dovetail.toml`: add a matching `standard-tag` (or an explicit Git dependency), then
list project names in `depends`. Import declarations by their **package** names.
For example, project `standard-json` exposes package `standard.json`.

See [Dependency Management](https://dovetaillang.org/book/tool-commands.md#23-dependency-management) for a full
manifest. The examples here state their dependencies. In an initialized project,
replace `src/main.dove` with the whole example and set `root_package` to its `package`
name. Each example includes a test and can be checked, built, run, and tested.

## 22.1 Core Types

The [prelude source](https://github.com/somdoron/dovetail/blob/main/dovetail/prelude/src/) includes primitives, `String`, `Option`,
`Result`, `List`, `Array`, slices, `BigInt`, `Decimal`, and core traits such as
`Equatable`, `Comparable`, `Hashable`, and `Display`. These need no dependency or import.

Use `Option<T>` for ordinary absence and `Result<T, E>` for operations that can fail.
Private newtypes can validate data at construction. `@derive(Equatable)` opts a record
or enum into structural equality; equality is not automatically granted to every type.

**Complete example (checked in CI)** — no extra dependencies:

<!-- book-example: {"name": "core", "depends": []} -->
```dovetail
package core

newtype Quantity private = Int32

module Quantity =
    public function parse(value: Int32): Result<Quantity, String> =
        if value > 0 then Ok(Quantity(value))
        else Error("quantity must be positive")

    public function count(self): Int32 = self.value

function main(): Unit =
    assert Quantity.parse(3).require.count() == 3
    assert Quantity.parse(0).isError

test "quantity rejects zero" = main()
```

Here `.require` is appropriate in a test with a known value. In an application,
handle the error or propagate it with `try`/`orReturn`. See [Error Handling](https://dovetaillang.org/book/error-handling.md).

## 22.2 Collections

`[1, 2, 3]` creates an immutable `List<Int32>`. `[|1, 2, 3|]` creates a fixed-size,
mutable `Array<Int32>`. `Slice<T>` is a writable view of an array, and
`ReadonlySlice<T>` prevents writes through that view without freezing other aliases.

List `length` and indexed lookup traverse the list. Arrays provide indexed access
and a stored length. Choose arrays for bytes, mutation, and repeated random access;
lists are useful for immutable sequential processing.

The [standard-collection project](https://github.com/somdoron/dovetail/blob/main/standard-collection/src/) adds `ArrayList`,
`MutableMap`, `MutableSet`, `MutableQueue`, `MutableStack`, `Range`, and `StringBuilder`.
Several mutable collections currently require `Default` elements; maps require both
`Default` keys and values, plus `Hashable` and `Equatable` keys. Validated types may
not have a meaningful default. Check these bounds before choosing a collection.

**Complete example (checked in CI)** — `depends = ["standard-collection"]`:

<!-- book-example: {"name": "collections", "depends": ["standard-collection"]} -->
```dovetail
package collections

import standard.collection.MutableMap

function main(): Unit =
    let counts = MutableMap<String, Int32>.new()
    counts.put("apples", 3)
    assert counts.get("apples").require == 3
    assert counts.get("pears").isNone
    let values = [1, 2, 3].map((value: Int32) => value * 2)
    assert values.foldLeft(0, (sum: Int32, value: Int32) => sum + value) == 12
    let array = values.toArray()
    array[0] = 9
    assert values.head == 2

test "collections preserve the expected values" = main()
```

Some existing collection constructors are named `new`; use the actual library API
even though new application APIs conventionally use `make`.

## 22.3 Text Processing

`String` is UTF-8 text. Its prelude module provides interpolation, comparison,
searching, and conversion to bytes or characters. Concatenate strings with `++`.
`standard.text.Charset` names encodings; currently it contains `Utf8`.
`standard.encoding` provides `Base64` and `Hex` codecs with typed decoding errors.
`standard.parser` provides composable parsers; see [Parser Composition](https://dovetaillang.org/book/tuple-extension.md#255-parser-composition).

**Complete example (checked in CI)** — `depends = ["standard-encoding"]`:

<!-- book-example: {"name": "encoding", "depends": ["standard-encoding"]} -->
```dovetail
package encoding

import standard.encoding.Base64

function main(): Unit =
    let bytes = "hello".bytes()
    let encoded = Base64.encode(bytes)
    assert encoded == "aGVsbG8="
    assert Base64.decode(encoded).require.readonly == bytes.readonly

test "base64 round trips bytes" = main()
```

Byte chunks are not necessarily complete UTF-8 characters or complete protocol
messages. Preserve incomplete input when implementing a streaming decoder.

## 22.4 Math

`BigInt` and `Decimal` are prelude types, with `big` and `dec` literal suffixes.
Decimal literals are constructed exactly from source digits. Both types support
addition, subtraction, multiplication, negation, equality, and ordering. Decimal
division and rounding operations are not provided yet. Normalization removes
insignificant trailing zeros; Decimal is not a fixed-display-scale money type.

The [standard-math project](https://github.com/somdoron/dovetail/blob/main/standard-math/src/) currently provides
`RoundingMode`; the presence of that enum does not imply a Decimal
rounding API.

**Complete example (checked in CI)** — no extra dependencies:

<!-- book-example: {"name": "decimal", "depends": []} -->
```dovetail
package decimal

function main(): Unit =
    assert 0.1dec + 0.2dec == 0.3dec
    assert 19.99dec * 3dec == 59.97dec
    assert 12345678901234567890big + 1big == 12345678901234567891big

test "decimal arithmetic is exact" = main()
```

## 22.5 I/O

`standard.io` supplies `Async<T, E>`, `Resource<T, E>`, fibers, synchronization, and
console/byte-stream I/O. An async value describes work; constructing or discarding
it does not run it. Use `await` inside async code and `.run()` at the application
boundary. Acquire resources with `use` so their cleanup is scoped.

**Complete example (checked in CI)** — `depends = ["standard-io"]`:

<!-- book-example: {"name": "console", "depends": ["standard-io"], "stdout": "Hello from async I/O!\n"} -->
```dovetail
package console

import standard.io.Async
import standard.io.Console
import standard.io.ConsoleError

async function greet(): Async<Unit, ConsoleError> =
    await Console.writeLine("Hello from async I/O!")

function main(): Unit = greet().run()

test "an async result can be consumed" =
    let program: Async<Unit, Never> = async do
        assert (await Async.succeed(42)) == 42
    program.run()
```

Console failures remain in the typed error channel. `Console.writeLine` is an async
operation; there is no synchronous `Console.println`. The prelude's `debug` is a
separate diagnostic convenience.

`standard.io.fs` adds `Path`, file/directory operations, and file streams.
`standard.io.log` adds structured logging. `dovetail run` needs filesystem grants
for file access; see [runtime permissions](https://dovetaillang.org/book/tool-commands.md#runtime-permissions).
See [Resource Management](https://dovetaillang.org/book/resources.md) for release and cancellation rules.

## 22.6 Networking

| Project | Package | Purpose |
|---|---|---|
| `standard-uri` | `standard.uri` | URI representation and parsing |
| `standard-http` | `standard.http` | HTTP/1.1 protocol codec without I/O |
| `standard-io-net` | `standard.io.net` | Async TCP networking |
| `standard-io-http` | `standard.io.http` | HTTP/HTTPS client, server, routing, buffered bodies |
| `standard-tls` | `standard.tls` | TLS 1.3 protocol implementation |
| `standard-io-crypto` | `standard.io.crypto` | Async TLS streams and managed crypto resources |

Use `dovetail run <project> --allow-network` for programs that open sockets or resolve
names. HTTP has basic routing; it is not a complete web framework. The HTTP/TLS
stack has outstanding hardening and conformance work. Read the
[HTTP readiness inventory](https://github.com/somdoron/dovetail/blob/main/docs/http-library-production-readiness.md) and the
[TLS implementation boundaries](https://github.com/somdoron/dovetail/blob/main/docs/tls-library-design.md) before relying on it
for production workloads. Some older HTTP inventory entries lag the source; the
inventory is not a guarantee that a listed feature is absent or complete.

## 22.7 Time

`standard.time` provides values such as `Duration`, `Instant`, calendar dates, times,
and time zones. Constructing or comparing those values is pure; obtaining the
current time is I/O through the clock APIs. Pass time into business rules so tests
can choose it explicitly.

**Complete example (checked in CI)** — `depends = ["standard-time"]`:

<!-- book-example: {"name": "time", "depends": ["standard-time"]} -->
```dovetail
package time

import standard.time.Duration
import standard.time.Instant

function main(): Unit =
    let start = Instant.ofEpochSecond(1700000000i64)
    let later = start.plus(Duration.ofSeconds(60i64))
    assert later == Instant.ofEpochSecond(1700000060i64)

test "time arithmetic uses an explicit instant" = main()
```

For deterministic tests, `standard.io.TestClock` supplies scoped virtual time to
the time extensions, `Async.sleep`, and `timeout`, with real-clock fallback outside
the installation. See [Scoped Test Clocks](https://dovetaillang.org/book/resources.md#139-scoped-test-clocks).

## 22.8 JSON

`standard.json.Json` is a JSON value tree. `Json.parse` returns a `Result`;
`json.encode()` serializes the tree. `JsonEncoder` and `JsonDecoder` support typed
conversion, and derives can generate implementations for public data shapes.
The decoder macro currently emits unqualified `Json` and `JsonError` names; import
both alongside the traits, as in the example.

**Complete example (checked in CI)** — `depends = ["standard-json"]`:

<!-- book-example: {"name": "json", "depends": ["standard-json"]} -->
```dovetail
package json

import standard.json.Json
import standard.json.JsonEncoder
import standard.json.JsonDecoder
import standard.json.JsonError

@derive(Equatable)
@derive(JsonEncoder)
@derive(JsonDecoder)
record Message =
    text: String
    identifier: Int64

function main(): Unit =
    let original = Message { text = "hello"; identifier = 9007199254740993i64 }
    let wire = original.toJson().encode()
    let decoded = Message.fromJson(Json.parse(wire).require).require
    assert decoded == original

test "a record round trips through JSON" = main()
```

`Json.Number` contains a `JsonNumber`, which retains either an exact `Int64` or a
finite `Float64`. Ordinary `Int32`/`Int64` fields and derived codecs preserve every
valid integer through encoding and parsing; no application wrapper is needed.

Integer tokens are parsed directly from decimal digits with checked arithmetic.
An integer token outside Int64 fails during parsing with `JsonError.OutOfRange("Int64")`,
even in a nested collection. There is no BigInt or exact-decimal JSON storage.
`Int32` decoding additionally checks its own range with `OutOfRange("Int32")`.

Decimal points and exponents select floating-point storage. Integer decoders reject
**all** float nodes with `JsonError.TypeError("Integer", "Float")`, including `1.0`,
`1e3`, `10e-1`, and fractions whose binary64 approximation is integral. Quoted numbers
remain strings and are not coerced. This policy prevents prior floating-point rounding
from making an invalid integer input appear valid.

`JsonNumber.fromInt32` and `fromInt64` construct numbers exactly; `toInt32` and
`toInt64` return checked Results. `JsonNumber.parse` validates a complete numeric
token without whitespace. Construction of the `JsonNumber` enum is private: use
these helpers instead of constructing its `Integer` or `Float` variants directly.

`JsonNumber.fromFloat64` rejects NaN/infinity with `OutOfRange("finite Float64")`.
Float parsing rounds to binary64, preserves signed zero and subnormals, allows
underflow to signed zero, and rejects overflow to infinity with that same error.
`Float64.fromJson` and `JsonNumber.toFloat64` accept both numeric categories;
converting large integers to Float64 can lose precision. Float serialization retains
a decimal point or exponent, so a whole-valued float stays a float after parsing.
Original numeric spelling is not preserved.

The infallible `Float64.toJson()` convenience encoder maps NaN/infinity to `Json.Null`,
also in derived fields. Use `JsonNumber.fromFloat64` and propagate its Result when
non-finite values must fail explicitly.

**Migration from 0.1.3:** replace `Json.Number(42.0)` with
`Json.Number(JsonNumber.fromFloat64(42.0).require)` for a known finite float, or
`42.toJson()` for an integer. Code matching `Json.Number(number)` now receives
`JsonNumber`; use its conversion helpers. Integral floats no longer decode as
integers. `JsonError.NonIntegralNumber` remains as a legacy variant but is no longer
returned by the primitive decoders. Integer JSON text remains unquoted decimal.

Private construction is also respected: a generated decoder cannot bypass a private constructor. Decode a
public input shape, then validate it through the private type's module.

## 22.9 Randomness and Crypto

The `wasi` project exposes host randomness through `standard.wasi.random`.
`standard.crypto` contains cryptographic primitives; `standard.crypto.roots` holds
trust anchors. `standard.io.crypto` supplies effectful random-key generation,
certificate loading, and resource-managed secrets.

Randomness and secret generation belong at the I/O boundary. Inject generated
identifiers into domain logic. Consult the [crypto design and implementation status](https://github.com/somdoron/dovetail/blob/main/docs/crypto-library-design.md)
for supported primitives and cleanup limitations; do not infer full protocol
readiness from the existence of a primitive.

## 22.10 Streams and SQLite

`standard-io-stream` exposes `standard.io.stream.Stream`. It supports chunked sources,
transformations, sequential composition, concurrent merging, resource lifetimes,
and terminal consumers. See [Streams](https://dovetaillang.org/book/streams.md) for backpressure and ownership
rules. `runCollect()` retains the whole result; use a fold or output consumer for
large or unbounded sources.

`standard-sqlite` exposes `standard.sqlite`, bringing a prebuilt SQLite component
and its generated bindings transitively. Connections/statements are resources;
queries return async values. See the complete [SQLite example](https://dovetaillang.org/book/components.md#173-using-sqlite)
for parameters and transactions. The current SQLite build has filesystem-locking
limitations and no WAL mode. Postgres and Redis clients are not provided yet.


## 22.11 YAML

Project `standard-yaml` exposes `standard.yaml`. It reads a documented subset of
YAML 1.2 Core into a source-located tree, then decodes that tree into application
types. Read files using the existing IO APIs and pass their text to `Yaml.parse`;
YAML parsing itself performs no IO.

**Complete example (checked in CI)** — `depends = ["standard-yaml"]`:

<!-- book-example: {"name": "yaml", "depends": ["standard-yaml"]} -->
```dovetail
package yaml

import standard.yaml.Yaml
import standard.yaml.YamlDecoder
import standard.yaml.YamlError

@derive(YamlDecoder)
record ServerConfig =
    host: String
    port: Int32
    workers: Option<Int32>

function readConfig(text: String): Result<ServerConfig, YamlError> =
    let yaml = try Yaml.parse(text)
    ServerConfig.fromYaml(yaml)

function main(): Unit =
    let config = readConfig("host: localhost\nport: 8080\n").require
    assert config.host == "localhost"
    assert config.port == 8080
    assert config.workers.isNone

test "read a typed YAML configuration" = main()
```

Import `Yaml` and `YamlError` alongside `YamlDecoder`: generated implementations
use these names, just as the JSON derives use `Json` and `JsonError`.

### Supported input

The reader supports nested block and flow mappings/sequences, compact sequence
entries, indentationless sequences as mapping values, plain and quoted strings,
YAML double-quoted escapes, comments, and multiline strings. Literal (`|`) and
folded (`>`) strings support chomping (`+`/`-`) and indentation indicators. Mapping
keys must be strings and fit on one line. Duplicate decoded keys are errors.

Unquoted scalars follow YAML 1.2 Core resolution: null, booleans, signed decimal
integers, unsigned hexadecimal/octal integers, and decimal/exponent floats,
including `.inf` and `.nan` spellings. `yes`, `no`, `on`, `off`, and dates remain
strings; quote numeric or boolean-looking mapping keys to make them strings.
Integers retain exact `Int64` values and overflow is an error. Floats round to
`Float64`, including subnormals, signed zero, and overflow to infinity.
Integer decoders accept only integer nodes: decimal/exponent float spellings such
as `1.0` and `1e3` produce `TypeMismatch`, even when mathematically integral.
`Int32` decoding checks its narrower range and returns `OutOfRange("Int32")`.
Derived integer fields use these same checks and preserve exact `Int64` values.
Leading zeros are decimal (`012` is 12); `+42` is accepted. Hexadecimal `0x` and
octal `0o` forms are unsigned and still limited to Int64.MAX. Signed radix forms,
`0b` binary syntax, and underscore separators remain strings, so integer decoding
fails with `TypeMismatch`. Quoted numeric text also remains a string.
A record decoded from YAML can use derived JSON codecs to persist Int64 fields
exactly; depend on both projects and import both sets of derive dependencies.

`Yaml.parse` accepts one document with optional `---` and `...` markers, an
optional leading BOM, and LF/CRLF line endings. Empty input produces null.
Nesting is limited to 128 collection levels. Anchors, aliases, explicit tags,
directives, complex/non-string keys, merge keys, and additional documents are
rejected. This is a YAML subset, not a complete YAML implementation. There is no
encoder or API for preserving comments and formatting.

### Typed decoding and diagnostics

`@derive(YamlDecoder)` supports records, enums, transparent newtypes, and generic
types. Record decoders reject unknown fields. Missing required fields fail;
missing or null `Option<T>` fields decode to `None`. No field defaults are inferred.
The `fromMissing()` trait hook defaults to failure, while `Option<T>` supplies
`None` and transparent newtypes delegate to their inner decoder. This also works
when a generic field is instantiated with an optional type.

Built-in decoders cover `Bool`, `String`, `Int32`, `Int64`, `Float64`, `Option<T>`,
`List<T>`, `Array<T>`, tuples of arity two through six, and `Yaml` itself. Integer
narrowing checks range; floats do not silently truncate to integers. An integer
can decode as `Float64`, which may lose precision for large integer values.

Enums use the same shapes as the JSON derives: `type` names the variant, a single
positional payload goes in `value`, multiple positional payloads use a sequence
in `value`, and named payload fields appear alongside `type`. Unknown variants,
unknown fields, wrong payload lengths, and named payload fields conflicting with
`type` are rejected.

`Yaml` contains a `YamlValue` and optional `YamlSpan`; collections retain child
nodes and mappings retain key nodes. `Yaml.make` constructs a node without a source
location. For custom decoding, `yaml.field<T>(name)` applies missing-field policy
and adds error context; `yaml.checkFields(names)` enforces the allowed field set.
`YamlError` carries a structured kind, optional span, and field/index path.
`error.format()` renders messages such as
`servers[2].port: expected Integer, got String at line 8, column 11`.
Positions count Unicode scalars: offsets are zero-based and lines/columns are
one-based. Handle parse and decode errors as `Result` values at file boundaries.
Decode public input shapes before applying domain validation; derives do not
bypass private construction rules.


---

# Part 23: Best Practices

Source: https://dovetaillang.org/book/best-practices/


## 23.1 Code Style

Run `dovetail fmt` and let it choose layout. Use camelCase identifiers, descriptive
names, and `.dove` filenames. A file containing one type's module can use that type's
name, such as `Order.dove`; other source filenames use camelCase. Name new factory
functions `make`, or `parse` when construction validates external input. Existing
libraries may use different names; call the API they actually expose.

Keep examples and application code explicit about their dependencies. Import named
extensions before using their methods, including within the same package.

## 23.2 Functional Patterns

Use records and enums for immutable domain data. Represent mutually exclusive states
with enum variants carrying the fields each state requires. Use private newtypes
when values must be validated before use. Private records reserve construction and
`with` updates for their associated module.

Record fields are immutable bindings, not a deep freeze: a record holding an array
or a mutable class still shares that object's state. Prefer lists or other immutable
contents when the model requires immutable snapshots.

Use classes for owned mutable state. Keep mutation behind a small API. A type's
shape and its behavior should make valid transitions easy to identify.

## 23.3 Error Handling Patterns

Use `Option` for expected absence, and `Result` for an operation that may fail. In
async code, keep failures in the `Async<T, E>` error channel. Handle an outcome,
return it, or compose it into more work. An exhaustive match forces new outcomes to
be considered when the model changes.

Warnings catch discarded `Result`, `Async`, and `Resource` expressions. Use
`let _ = expression` only when deliberately ignoring that value. It neither awaits
an async computation nor acquires a resource. Assigning to a named variable is not
proof that the variable will later be used; these warnings are not a general
unused-variable analysis.

Reserve `panic`, `assert`, and `.require` for bugs, tests, and established invariants.
A synchronous panic terminates execution; async code can represent a panic in its
failure cause and run scoped cleanup. Panics are not the normal input-validation API.

Use `use` for external resources. Keep acquisition and release bounded, and choose
`fork` versus `forkBackground` according to whether a child should finish normally
or be cancelled when its scope ends. Read [Resources](https://dovetaillang.org/book/resources.md) and
[Async Programming](https://dovetaillang.org/book/async.md) before building long-lived services.

## 23.4 Project Organization

Start with one project. Split packages or projects when they represent a real
boundary, and keep dependencies acyclic. Tests next to a rule make it easy to change
them together; integration tests belong in `test/`.

Keep I/O at the edges of business rules. Pass facts, clocks, and generated IDs as
values. Give persistence and transport adapters interfaces owned by their consumers.
For larger applications, see [Project Structure](https://dovetaillang.org/book/project-structure.md) and
[The Domain Layer](https://dovetaillang.org/book/ddd.md).

Check in the manifest and dependency lockfile. Format, check, and test in CI using
a matching compiler version. Start from [Tool Commands](https://dovetaillang.org/book/tool-commands.md#24-ci-and-local-compiler-development)
for the command sequence.


---

# Part 24: Prefixed String Literals

Source: https://dovetaillang.org/book/prefixed-literals/


A **prefixed string literal** is a string with an identifier attached to its opening quote:

```dovetail
let query = sql"SELECT * FROM users WHERE id = $id"
```

The prefix selects a *handler*: a library type that decides what the literal means. The compiler owns the syntax — how the literal is lexed, and what `$` may do inside it — and nothing else. It has no idea what SQL is.

This is the same bargain as derive macros ([Part 16](https://dovetaillang.org/book/macros.md)): the compiler provides a small structural hook, and libraries provide the meaning.

---

## 24.1 Why not just build a string?

Because a string that is *interpolated* and a string that is *parameterized* are different things, and only one of them is safe:

```dovetail
// An ordinary string: the name is spliced into the text.
let bad = "SELECT * FROM users WHERE name = '$name'"

// A prefixed literal: the name is bound as a parameter.
let good = sql"SELECT * FROM users WHERE name = $name"
```

The second renders to `SELECT * FROM users WHERE name = ?` with `name` carried alongside as a bound parameter. There is no syntax for splicing a value into the text, so SQL injection is not expressible — not "discouraged", not "caught by a lint".

The same shape suits any language-inside-a-language: a regex whose interpolations are escaped, a shell command whose interpolations are quoted, a query whose interpolations are bound.

---

## 24.2 Syntax

The prefix must touch the quote — `sql"..."`, never `sql "..."`. With a space, you get an ordinary identifier followed by an ordinary string.

Both quote forms work:

```dovetail
let one = sql"SELECT 1"

let many = sql"""
    SELECT u.id, u.name
    FROM users u
    WHERE u.total > $minTotal
"""
```

As with ordinary `"""` strings, one leading newline after the opener is dropped and the rest of the text is kept verbatim — there is no indentation stripping.

### Interpolation

Three forms are available inside a prefixed literal:

| Form | Meaning |
|------|---------|
| `$ident` | interpolate a bare identifier |
| `${ expr }` | interpolate any expression |
| `$..expr` | *spread*: interpolate a sequence of values |

`$ident` binds a bare name only. Anything with a field access, a call, or an operator needs the braced form:

```dovetail
let q = sql"WHERE name = ${user.name} AND age > ${minAge + 1}"
```

`$..` exists only in prefixed literals — an ordinary string has no builder to hand a sequence to, and using it there is an error that says so.

Escape sequences work exactly as in ordinary strings, so `\$` is a literal dollar sign and `\n` is a newline. That does mean a backslash-heavy literal (a regex, say) needs its backslashes doubled.

---

## 24.3 What a literal lowers to

The compiler rewrites the literal into a chain of ordinary method calls on the type the prefix names:

```dovetail
sql"WHERE id = $id AND tag IN ($..tags)"
```

becomes

```dovetail
SqlBuilder.empty()
    .literal("WHERE id = ")
    .value(id)
    .literal(" AND tag IN (")
    .spread(tags)
    .literal(")")
    .build()
```

Those five method names are the entire contract. Text between interpolations becomes `literal`, a `$` becomes `value`, a `$..` becomes `spread`, and `build` produces the final value.

The chain is then type-checked like any hand-written code, which is what makes the next section work.

---

## 24.4 Bounds come from the builder, not the compiler

The builder's own signatures decide what may be interpolated:

```dovetail
public function value<T>(self, item: T): SqlBuilder where T: ToSqlValue =
    ...
```

Because `value` is what the lowering calls, `T: ToSqlValue` is enforced at every interpolation site — and the compiler enforces it without knowing that `ToSqlValue` exists. Interpolating a type that doesn't implement it is an ordinary trait-bound failure, reported at the interpolation itself:

```
error: type 'Widget' does not implement trait 'ToSqlValue' required by constraint on 'T'
   |
   |     let q = sql"WHERE thing = $widget"
   |                               ^
```

Swap the bound in the builder and you have changed what the literal accepts. No compiler change is involved.

---

## 24.5 Writing a builder

A builder is an ordinary type with five methods. The `@stringLiteral` declaration associates a prefix with its builder.

```dovetail
public record Frag =
    text: String
    values: Array<String>

public record Builder =
    text: StringBuilder
    values: ArrayList<String>

module Builder =
    public function empty(): Builder =
        Builder { text = StringBuilder.new(); values = ArrayList<String>.new() }

    public function literal(self, chunk: String): Builder =
        self.text.append(chunk)
        self

    public function value<T>(self, item: T): Builder where T: Display =
        self.text.append("?")
        self.values.add(item.format())
        self

    public function spread<T>(self, items: Array<T>): Builder where T: Display =
        ...

    public function build(self): Frag =
        Frag { text = self.text.toString(); values = self.values.toArray() }
```

Two things are worth getting right:

- **Keep the builder type non-generic; make only `value` and `spread` generic.** This keeps the builder state independent of each interpolated value's type, while allowing each value method to express its own trait bounds.
- **Mutate, don't copy.** Returning `self` after appending to a `StringBuilder` makes an N-part literal cost O(total bytes). Rebuilding an immutable record at each step makes it O(N²).

All five methods must be `public`.

---

## 24.6 Declaring a prefix

A prefix is declared with `@stringLiteral`, which takes no argument — the prefix *is* the declared name:

```dovetail
@stringLiteral
public type sql = SqlBuilder
```

The marker usually goes on a lowercase **type alias**, so the builder keeps its descriptive name while the prefix reads the way it should at the use site. It may also go directly on a `record` or `class` whose own name is the prefix.

### The prefix is an ordinary name

This is the whole design. `sql"..."` is available exactly where `sql` is in scope:

```dovetail
import standard.sqlite.sql

let query = sql"SELECT * FROM users WHERE id = $id"
```

Three things fall out of that, none of which needed inventing:

**Collisions are impossible.** Two libraries may both export a `sql`. A file imports the one it wants; there is no global claim to arbitrate, no precedence rule, and no manifest override.

**Aliasing renames the literal.** `import` already renames, so:

```dovetail
import standard.sqlite.sql
import com.pg.sql as pg

let a = sql"SELECT 1"
let b = pg"SELECT 1"
```

**It is self-documenting.** A reader sees the import at the top of the file and knows exactly which library `sql"..."` comes from — something a build-config entry in a different project could never tell them.

A name that is in scope but was not marked `@stringLiteral` is not a prefix, and says so. A prefix that is not in scope points at the import that would fix it.

> `test` cannot be a prefix: `test "name" = ...` already declares a test, and a space-less `test"name"` must keep meaning that.

---

## 24.7 Composition instead of in-string control flow

There is deliberately no conditional form inside a literal. Since the built value is an ordinary value, conditional and dynamic construction is ordinary code — and the library, not the language, decides what "compose" means:

```dovetail
let query =
    sql"SELECT * FROM users"
        ++ Query.whereAndSome([
            nameFilter.map<Query>((name: String) => sql"name = $name"),
            statusFilter.map<Query>((status: Status) => sql"status = $status")
        ])
```

Inside the lambda, `name` is a plain `String` bound by an ordinary parameter. An in-string conditional would have needed the compiler to rebind an interpolated name to its unwrapped type — a typing rule specific to one library, in the compiler, forever.

Composition gets the same result with nothing new in the language, and gets *more*: `whereAndSome` drops the absent filters and emits no `WHERE` at all when they are all absent, so there is no `WHERE 1=1` placeholder to write. None of that is the literal's business — `Query`, `whereAndSome`, and the `++` operator (via the prelude's `Concat` trait) are all ordinary library code that the compiler knows nothing about.

---

## 24.8 Summary

| | |
|---|---|
| `prefix"..."` / `prefix"""..."""` | A prefixed literal; the prefix must touch the quote |
| `$ident`, `${ expr }` | Interpolate a value → `builder.value(expr)` |
| `$..expr` | Spread a sequence → `builder.spread(expr)` |
| Literal text | → `builder.literal("...")` |
| Builder contract | `empty`, `literal`, `value`, `spread`, `build`, all `public` |
| Declaration | `@stringLiteral` on a type alias, record, or class; the prefix is the declared name |
| Scope | Wherever the name is imported; `import pkg.sql as pg` renames the literal to `pg"..."` |

See [docs/SQL.md](https://github.com/somdoron/dovetail/blob/main/docs/SQL.md) for the first client of this mechanism, `standard-sqlite`'s `sql"..."`.


---

# Part 25: Tuple Extension (Advanced)

Source: https://dovetaillang.org/book/tuple-extension/


Tuple extension lets generic code build tuples and define behavior across tuple
arities. This chapter assumes familiarity with [tuples](https://dovetaillang.org/book/type-system.md#64-tuples),
[generics](https://dovetaillang.org/book/generics.md), and [trait implementations](https://dovetaillang.org/book/traits.md).

## 25.1 Extending a Tuple

Use binary `~` to append one element. A non-tuple left operand forms a pair;
a tuple left operand grows by one element:

```dovetail
let pair = 1 ~ true                 // (1, true)
let triple = pair ~ "hello"         // (1, true, "hello")
let nested = pair ~ ("a", "b")      // (1, true, ("a", "b"))
```

The right operand always remains one element. Chaining associates to the left,
so `1 ~ 2 ~ 3` produces `(1, 2, 3)`. Both operands execute once, left to right.

`~` binds below comparisons, so compare an extension result with parentheses:
`(1 ~ true) == (1, true)`. Prefix `~` still means bitwise negation.

## 25.2 Extension in Generic Types

The same operator works in types and generic functions:

```dovetail
function append<T, U>(left: T, right: U): T ~ U = left ~ right
```

The compiler determines the result shape from `T`; no bound or overload is
required. With `T = Int32` and `U = Bool`, the result is `(Int32, Bool)`.
With `T = (Int32, Bool)` and `U = String`, it is `(Int32, Bool, String)`.
While the outer shape of `T` is unknown, the compiler preserves `T ~ U` until
substitution reveals that shape.

Ordinary pair types behave differently: `(T, U)` always has two outer elements.
Substituting a tuple for `T` preserves it as the first element of that pair.

Infer extension operands from ordinary function arguments or supply explicit
type arguments. Reverse inference from an extension result is currently
supported only for the tuple-constrained form described below.

## 25.3 Tuple Shape and Accessors

`Tuple` is a built-in constraint for actual tuples of at least two elements.
Aliases to tuples satisfy it; records and nominal wrappers around tuples do
not. It is usable in `where` bounds, and cannot be implemented, inherited, or
used as a runtime interface type.

Every tuple has `.init` and `.last`:

```dovetail
(1, true).init              // 1
(1, true).last              // true
(1, true, "x").init         // (1, true)
(1, true, "x").last         // "x"
((1, true), "x").init       // (1, true), the first element intact
```

Each accessor evaluates its receiver once. For a pair, `.init` returns the
first element. For a larger tuple, it returns the prefix tuple. `.last` always
returns the final element.

For an unknown `T: Tuple`, the compiler defers the accessor's result type until
it knows the shape. A tuple bound alone does not prove that `.init` returns a
tuple, and it says nothing about the traits implemented by individual elements.

For an actual extension `T ~ U`, `.init` has type `T` and `.last` has type `U`,
even without a bound on `T`:

```dovetail
function prefix<T, U>(left: T, right: U): T = (left ~ right).init
```

Reconstructing an arbitrary tuple with these accessors requires care. If a
pair's first element is itself a tuple, extension flattens that first element:

```dovetail
let pair = ((1, true), "x")
let preserved = (pair.init, pair.last) // ((1, true), "x")
let extended = pair.init ~ pair.last  // (1, true, "x")
```

## 25.4 Pair and Recursive Implementations

A trait can handle tuple arities with a pair case `(A, B)` and a recursive
case `T ~ U where T: Tuple`. The tuple bound guarantees that the recursive case
has at least three outer elements. The pair case matches exactly two, including
pairs whose first element is another tuple.

This example counts outer elements:

```dovetail
trait Arity =
    function arity(self): Int32

implement <A, B> Arity for (A, B) =
    function arity(self: (A, B)): Int32 = 2

implement <T, U> Arity for T ~ U where T: Tuple, T: Arity =
    function arity(self: T ~ U): Int32 = self.init.arity() + 1
```

| Actual type | Implementation | Bindings |
|---|---|---|
| `(Int32, Bool)` | Pair | `A = Int32`, `B = Bool` |
| `(Int32, Bool, String)` | Recursive | `T = (Int32, Bool)`, `U = String` |
| `((Int32, Bool), String)` | Pair | `A = (Int32, Bool)`, `B = String` |

Selection does not depend on declaration order or implementation priority.
A concrete triple implementation of `Arity` would overlap the recursive case
and is rejected. Ordinary user-trait bounds cannot establish that two
implementations are disjoint; `Tuple` supplies a specific structural arity fact.

Supported symbolic implementation heads have exactly the form `T ~ U`, with
both operands declared as implementation parameters and `T: Tuple`. Unconstrained
or chained symbolic heads are not supported.

The prelude's `Equatable`, `Hashable`, `Default`, `Comparable`, and `Display`
use pair/recursive implementations. Equality stops at the first unequal element;
hashing combines elements in order; defaults are constructed element by
element. Ordering is lexicographic, and formatting preserves flat versus nested
tuple punctuation.

## 25.5 Parser Composition

In `standard.parser`, `left.append(right)` and `left ++ right` sequence parsers
and extend their successful results. For example:

```dovetail
let parser = parseChar('(') ++ parseDigit() ++ parseChar(')')
```

Its successful result has type `(Char, Char, Char)`. As with value extension,
a tuple returned by the right parser remains one element.

`zip` keeps both results intact as a pair. Use `zipLeft` or `zipRight` when
one result, such as a delimiter, should be discarded.

## 25.6 Enclosing Parameter Bounds

An individual method can require that an enclosing parameter is a tuple:

```dovetail
record TupleBox<T> = value: T

module TupleBox<T> =
    function append<U>(self: TupleBox<T>, other: U): T ~ U where T: Tuple = self.value ~ other
```

This method returns a tuple of at least three elements. A `TupleBox<Int32>`
can still be constructed, but its `append` method cannot be called because
`Int32` does not satisfy `Tuple`.

The bound is a requirement chosen by this method; the `~` operator itself
continues to accept a scalar left operand. The method's signature, body, and
closures can all use its tuple proof. A generic caller must carry a matching
proof, and taking a method reference checks the same requirement as a call.
The [advanced generics chapter](https://dovetaillang.org/book/advanced-generics.md#263-bounds-on-enclosing-parameters) explains
the rules for modules, classes, implementations, and extension blocks.

For the compiler design and implementation milestones, see the
[tuple extension design](https://github.com/somdoron/dovetail/blob/main/docs/tuple-extension-design.md).


---

# Part 26: Advanced Generics

Source: https://dovetaillang.org/book/advanced-generics/


This chapter covers generic library design, method-specific requirements, and
runtime type matching. Read [Generics](https://dovetaillang.org/book/generics.md),
[Traits and Implementations](https://dovetaillang.org/book/traits.md), and [Classes](https://dovetaillang.org/book/classes.md) first.
The examples build on the basic type parameters and `where` clauses from Part 7.

## 26.1 Generic Extensions

You can write extensions that work with generic types. As with other extensions,
give the extension a name and import it before using its methods:

```dovetail
package example

import example.ArrayHelpers

extension ArrayHelpers<T> for Array<T> =
    function isEmpty(self): Bool =
        self.length == 0

    function first(self): Option<T> =
        if self.isEmpty() then
            None
        else
            Some(self[0])

function main(): Unit =
    let numbers = [|1, 2, 3|]
    assert numbers.isEmpty() == false
    assert numbers.first() == Some(1)
```

---

## 26.2 Class Constraints

Use `where T: class` when an operation needs class identity:

```dovetail
function sameInstance<T>(left: T, right: T): Bool where T: class =
    ClassIdentity.equals(left, right)

function instanceHash<T>(value: T): Int64 where T: class =
    ClassIdentity.hash(value)
```

The bound permits concrete and generic classes, aliases of classes, and generic parameters already constrained by `class`. A superclass bound such as `where T: Animal` also satisfies it. A `Box<Int32>` is a class even though its element type is not.

Records, enums, arrays, newtypes, primitives, `Any`, and interface objects do not satisfy `class`. The bound grants neither constructors nor arbitrary members, and it does not automatically implement `Equatable` or `Hashable`.

Combine it with trait bounds using `where T: class + Display`. An unconstrained generic function cannot call the identity functions just because its current callers happen to pass classes. See [Class Identity](https://dovetaillang.org/book/classes.md#915-class-identity) for the equality and hash contracts.

A primitive subtype bound can restrict a method to a particular element type.
For example, `where T: Uint8` allows `ReadonlySlice<T>` to widen to
`ReadonlySlice<Uint8>`. It accepts `Uint8` and the uninhabited subtype `Never`;
it does not convert other integer types or imply the `class` constraint.
`Stream.writeToOutputStream` uses this bound to expose byte output directly on
its generic module.

---

## 26.3 Bounds on Enclosing Parameters

A method's `where` clause can constrain type parameters declared by its
enclosing module, class, implementation block, or extension block. The method
does not need to declare its own type parameters:

```dovetail
class Holder<T>(public value: T) =
    public function render(self): String where T: Display = self.value.format()
    public function unchanged(self): T = self.value
```

`render` requires `T: Display`; constructing a `Holder<T>` or calling `unchanged`
does not. The bound applies throughout the method's signature, body, and nested
closures, and does not become available to sibling methods.

Callers must satisfy these requirements when calling the method or taking a
method reference. Generic callers prove them using their own bounds:

```dovetail
function renderHolder<T>(holder: Holder<T>): String where T: Display = holder.render()
```

A method can use the class's type parameter together with a type parameter of
its own. For example, this box can search the value it holds:

```dovetail
trait Contains<Item> =
    function contains(self, item: Item): Bool

class SearchBox<T>(public value: T) =
    public function contains<U>(self, item: U): Bool where T: Contains<U> =
        self.value.contains(item)
```

Here, `T` is the type stored in the box. `U` is the type of item passed to
`contains`. Read `where T: Contains<U>` as: **the stored type must support
searching for this kind of item**.

For a concrete example, a range can contain integers:

```dovetail
record Range = start: Int32, end: Int32

implement Contains<Int32> for Range =
    function contains(self: Range, item: Int32): Bool =
        item >= self.start && item <= self.end

let box = SearchBox(Range { start = 1, end = 10 })
box.contains(5)       // T is Range, U is Int32: allowed; returns true
box.contains(true)    // U is Bool: rejected; Range does not implement Contains<Bool>
```

The same box keeps its stored type, `Range`, across calls. Each call chooses
the method's `U` from the item being searched for and checks the corresponding
`Contains<U>` requirement.

Use different names for the two parameters: declaring `contains<T>` here would
reuse the class's `T`, which the compiler rejects.

---

## 26.4 Trait and Override Contracts

An implementation must accept the calls that its trait promises to callers.
It cannot add an extra requirement to one of those methods. For example, the
compiler rejects this implementation:

```dovetail
trait Inspect =
    function inspect(self): Unit

record Box<T> = value: T

implement <T> Inspect for Box<T> =
    function inspect(self: Box<T>): Unit where T: Display = ()
```

The implementation says every `Box<T>` implements `Inspect`, but its method
would only work for some choices of `T`. A caller that knows only `Inspect`
has no way to satisfy that extra requirement.

Putting `where T: Display` on the **implementation block** instead restricts
which boxes implement `Inspect`. Every box that does implement the trait then
has the promised method.

The same rule applies to class overrides: a child method must accept the calls
allowed by its parent method. It cannot add an extra bound. A requirement
already guaranteed by the enclosing class or implementation block can be
repeated on the method.

An implementation also inherits the bounds declared on a generic trait method.
Renaming the method's type parameter, such as from `T` to `U`, does not remove
those requirements.

---

## 26.5 Variance and Method Bounds

Variance controls whether one use of a generic type can be assigned to another.
For example, every `Int32` value can be used as `Any`, but that does not by itself
mean a `Box<Int32>` can be used as `Box<Any>`.

### Plain Parameters, `out`, and `in`

With a plain parameter, such as `Box<T>`, different type arguments stay separate:
`Box<Int32>` cannot be assigned to `Box<Any>`. This is called **invariance**.

Use `out T` when the type provides values of `T`. A reader that produces integers
can be used where a reader of any values is expected:

```dovetail
class Reader<out T>(public value: T)

let integers = Reader(42)
let anyValues: Reader<Any> = integers
```

This is called **covariance**. The compiler checks that an `out` parameter is not
used where a caller could supply a value of that type, such as a method argument
or a mutable field.

Use `in T` when the type accepts values of `T`. Something that accepts any value
can also accept integers:

```dovetail
class Consumer<in T>() =
    public function accept(self, value: T): Unit = ()

let anyValues = Consumer<Any>()
let integers: Consumer<Int32> = anyValues
```

This is called **contravariance**. An `in` parameter cannot be used where the
caller receives a value of that type, such as a method return type. Start with
plain type parameters; add `in` or `out` when your API needs these conversions.

### Conditional Bounds on Virtual Methods

There is one restriction when combining these method bounds with `in` or `out`
on a class parameter. Consider this hypothetical declaration, which the compiler
rejects:

```dovetail
class Formatter<in T>() =
    public function render(self, value: T): String where T: Display = value.format()
```

Normally, `in T` lets you use a `Formatter<Any>` as a `Formatter<Int32>`: something
that accepts any value can also accept an integer. But that would cause a problem
here:

```dovetail
let original = Formatter<Any>()
let integers: Formatter<Int32> = original
integers.render(42)
```

The last call appears valid because `Int32` implements `Display`. However, the
object is still the original `Formatter<Any>`. Its `render` method is unavailable
because `Any` does not implement `Display`. Assigning the object to a differently
typed variable does not create a new object or a new implementation of its method.
A virtual call uses the method belonging to that original object.

To prevent this, use plain `T`, without `in` or `out`, when a virtual method adds
a requirement on `T`:

```dovetail
class Formatter<T>() =
    public function render(self, value: T): String where T: Display = value.format()
```

Plain `T` is called **invariant**. It prevents the conversion from
`Formatter<Any>` to `Formatter<Int32>` shown above. The same restriction applies
to parameters mentioned inside a method's bound: for `where T: Contains<U>`,
both class parameters `T` and `U` must be invariant if the class does not already
guarantee that requirement.

Alternatively, require `Display` on the whole class:

```dovetail
class Formatter<in T>() where T: Display =
    public function render(self, value: T): String = value.format()
```

Now every allowed `Formatter<T>` has a working `render` method. You cannot
construct `Formatter<Any>` in the first place, so the problematic conversion
cannot arise. The class-level bound does not impose the extra invariance rule;
the usual rules for `in` and `out` still apply.

---

## 26.6 Pattern Matching on Generic Types

You can use pattern matching to check types at runtime. This is particularly useful in generic functions where you need to handle different types differently.

### Type Matching in Generic Functions

The most common use case is determining the actual type in a generic function:

```dovetail
record Box<T> =
    value: T

function getBoxType<T>(box: T): Int32 =
    match box with
        case _: Box<Int32> => 1
        case _: Box<String> => 2
        case _ => 0

let intBox = Box { value = 42 }
let strBox = Box { value = "hello" }

getBoxType(intBox)   // returns 1
getBoxType(strBox)   // returns 2
```

The `_: Type` syntax checks if the value has the specified type without binding it to a variable.

### Distinguishing User-Defined Types

Type patterns work with non-generic types too, letting you distinguish between different user-defined types:

```dovetail
record Cat = name: String
record Dog = name: String

function getAnimalType<T>(animal: T): Int32 =
    match animal with
        case _: Cat => 1
        case _: Dog => 2
        case _ => 0

let cat = Cat { name = "Whiskers" }
let dog = Dog { name = "Rex" }

getAnimalType(cat)  // returns 1
getAnimalType(dog)  // returns 2
```

### Matching Type Arguments

Use the type name with explicit type arguments in a pattern:

```dovetail
record Box<T> =
    value: T

function describeBox(box: Box<String>): Int32 =
    match box with
        case _: Box<String> => 1
        case _ => 0

let b = Box { value = "hello" }
describeBox(b)  // returns 1
```

### Matching with Custom Types

You can match on generic types instantiated with user-defined types:

```dovetail
record Person = name: String

record Container<T> =
    item: T

function checkContainer<T>(c: T): Int32 =
    match c with
        case _: Container<Person> => 1
        case _ => 0
```

### Matching Multiple Type Arguments

For types with multiple type parameters, specify all type arguments. This allows distinguishing between different instantiations:

```dovetail
record Pair<A, B> =
    first: A
    second: B

function getPairType<T>(p: T): Int32 =
    match p with
        case _: Pair<Int32, String> => 1
        case _: Pair<String, Int32> => 2
        case _: Pair<String, String> => 3
        case _ => 0

let p1 = Pair { first = 42; second = "hello" }
let p2 = Pair { first = "hello"; second = 42 }
let p3 = Pair { first = "a"; second = "b" }

getPairType(p1)  // returns 1
getPairType(p2)  // returns 2
getPairType(p3)  // returns 3
```

### Generic Enums

Pattern matching works with generic enums too:

```dovetail
enum Maybe<T> =
    Just(T)
    Nothing

function checkMaybe<T>(m: T): Int32 =
    match m with
        case _: Maybe<String> => 1
        case _: Maybe<Int32> => 2
        case _ => 0
```

### Generic Classes

And with generic classes:

```dovetail
class Wrapper<T>(value: T) =
    function get(self): T = self.value

function checkWrapper<T>(w: T): Int32 =
    match w with
        case _: Wrapper<String> => 1
        case _: Wrapper<Int32> => 2
        case _ => 0
```

### Distinguishing Different Generic Types

You can distinguish between different generic types that have the same type argument:

```dovetail
record Box<T> =
    value: T

record Wrapper<T> =
    inner: T

function getType<T>(x: T): Int32 =
    match x with
        case _: Box<Int32> => 1
        case _: Wrapper<Int32> => 2
        case _ => 0

let b = Box { value = 42 }
let w = Wrapper { inner = 42 }

getType(b)  // returns 1
getType(w)  // returns 2
```

### Binding Values in Type Patterns

You can bind the matched value to a variable:

```dovetail
record Box<T> =
    value: T

function processBox<T>(x: T): Int32 =
    match x with
        case box: Box<Int32> => box.value
        case box: Box<String> => box.value.length
        case _ => 0

let intBox = Box { value = 42 }
let strBox = Box { value = "hello" }

processBox(intBox)   // returns 42
processBox(strBox)   // returns 5
```

### Wildcard Fallback

The wildcard pattern `_` catches any type that doesn't match the specific patterns:

```dovetail
record Box<T> =
    value: T

function boxCode<T>(x: T): Int32 =
    match x with
        case _: Box<Int32> => 1
        case _: Box<String> => 2
        case _ => 99              // Fallback for other types

let b = Box { value = true }
boxCode(b)  // returns 99 (Box<Bool> falls through to wildcard)
```

---

## 26.7 Generic Trait Defaults

A default is a method body supplied by the trait. The implementing type can use
it by leaving that method out of its implementation block.

In this example, `pick<T>` is a **generic method**: each call chooses `T`.
The first call chooses `Int32`; the second chooses `String`. `Reader` itself has
no type parameters.

```dovetail
package example

trait Picker =
    function pick<T>(self, value: T): T = value

record Reader = id: Int32

implement Picker for Reader

function main(): Unit =
    let reader = Reader { id = 0 }
    assert reader.pick(42) == 42
    assert reader.pick("text") == "text"
```

A generic class can use the same default. Here `Reader<T>` has a class parameter,
and `pick<T>` has a separate method parameter. Creating `Reader(1)` fixes the
class parameter to `Int32`; it does not prevent `reader.pick("text")` from
choosing `String` for the method parameter.

```dovetail
package example

trait Picker =
    function pick<T>(self, value: T): T = value

class Reader<T>(id: T) implements Picker =
    public function get(self: Reader<T>): T = self.id

function choose<P, T>(picker: P, value: T): T where P: Picker = picker.pick(value)

function main(): Unit =
    assert choose(Reader(1), "bound") == "bound"
    let reader = Reader(1)
    assert reader.pick("text") == "text"
    assert reader.pick(42) == 42
```

An explicit matching method takes precedence over the default. Defaults may
also be properties. Calls from a default to another instance member observe
subclass overrides, just like calls from other class methods.

A generic default body can use only the operations justified by its declared
bounds. For example, a method comparing two values with `==` needs
`where T: Equatable`. Implementations cannot add stricter requirements than the
trait declares. Generic methods still cannot be dispatched through interface
values; use a generic function with a trait bound instead.

## 26.8 Associated Outputs

An associated type lets each implementation choose a type. `Producer` below says
that `produce()` returns its implementation's `Output`. `NumberProducer` chooses
`Int32` in its implementation block.

The generic helper does not need to choose that output type. `P.Output` means
“the output chosen by the `Producer` implementation for `P`.”

```dovetail
package example

trait Producer =
    type Output
    function produce(self): Output

record NumberProducer = value: Int32

implement Producer for NumberProducer =
    type Output = Int32
    function produce(self): Int32 = self.value

function read<P>(producer: P): P.Output where P: Producer =
    producer.produce()

function forward<P>(producer: P): P.Output where P: Producer =
    read(producer)

function main(): Unit =
    assert forward(NumberProducer { value = 42 }) == 42
```

For `NumberProducer`, both `read` and `forward` return `Int32`. Another producer
could choose `String`, and the same helpers would return `String` for it.

Inside `read`, the output is still unknown. It can be returned or passed to
another function expecting `P.Output`. It cannot be treated as `Int32` or used
in arithmetic merely because one implementation returns a number.

When a helper specifically needs a numeric output, state that requirement:

```dovetail
function readNumber<P>(producer: P): Int32
    where P: Producer<Output = Int32> =
    producer.produce()
```

Associated names are resolved through the parameter's trait bounds. If two
bounds give `P` different members named `Output`, `P.Output` is ambiguous.
Associated-type declarations cannot provide defaults: each implementation must
supply its associated definitions.

## 26.9 Generic Associated Types

Sometimes the implementation chooses a container, while each method call chooses
what goes inside it. That is the purpose of `type Wrapped<T>`.

Read the following example in three steps:

1. `Wrapper` requires a generic method `wrap<T>` and an associated type `Wrapped<T>`.
2. `OptionalWrapper` chooses `Option<T>`; `ArrayWrapper` chooses `Array<T>`.
3. `wrapValue` returns the container chosen by its `wrapper` argument, containing
   the type of its `value` argument.

```dovetail
package example

trait Wrapper =
    type Wrapped<T>
    function wrap<T>(self, value: T): Wrapped<T>

record OptionalWrapper = name: String
record ArrayWrapper = name: String

implement Wrapper for OptionalWrapper =
    type Wrapped<T> = Option<T>
    function wrap<T>(self, value: T): Option<T> = Some(value)

implement Wrapper for ArrayWrapper =
    type Wrapped<T> = Array<T>
    function wrap<T>(self, value: T): Array<T> = [|value|]

function wrapValue<W, T>(wrapper: W, value: T): W.Wrapped<T>
    where W: Wrapper =
    wrapper.wrap(value)

function main(): Unit =
    let optional = OptionalWrapper { name = "optional" }
    let array = ArrayWrapper { name = "array" }
    let numberOption: Option<Int32> = wrapValue(optional, 42)
    let numberArray: Array<Int32> = wrapValue(array, 42)
    let textOption: Option<String> = wrapValue(optional, "hello")
    let textArray: Array<String> = wrapValue(array, "hello")
    assert numberOption.require == 42
    assert numberArray == [|42|]
    assert textOption.require == "hello"
    assert textArray == [|"hello"|]
```

`W.Wrapped<T>` names the result without forcing every implementation to use the
same container. In the first call, `W` is `OptionalWrapper` and `T` is `Int32`,
so the result is `Option<Int32>`. In the second, `W` is `ArrayWrapper`, so the
result is `Array<Int32>`.

The associated definition does not have to use its parameter. An implementation
could choose `type Wrapped<T> = Int32` for every `T`. Therefore, knowing the
result type does not necessarily tell the compiler the input type. Supply type
arguments when the arguments to the call do not provide enough information.

### Generic Resource Helpers

`Usable<T, E>` uses an associated type `Wrapped<U, E2>` for the result of its
continuation. A helper accepting an unknown resource must preserve that result
contract. Its caller can provide a `finish` function returning the resource's
wrapper:

```dovetail
package example
newtype Holder = Int32
implement Usable<Int32, Never> for Holder =
    type Wrapped<U, E2> = U
    function use<U, E2>(self, f: (Int32) => U, errorF: (Never) => E2): U = f(self.value)
function scoped<R>(resource: R, finish: (Int32) => R.Wrapped<Int32, Never>): R.Wrapped<Int32, Never>
    where R: Usable<Int32, Never> =
    let value = use resource
    finish(value)
function main(): Unit = assert scoped(Holder(40), value => value + 2) == 42
```

`Holder` chooses `Wrapped<U, E2> = U`, so its continuation returns a plain
`Int32`. The generic `scoped` function cannot assume that choice for every
resource. Its `finish` parameter and return type both say
`R.Wrapped<Int32, Never>` to preserve the contract.

## 26.10 Inherited Overloads

A child trait can add a method whose name is already used by a parent when the
parameter lists differ. The implementation supplies both methods. The argument
type determines which one a call selects:

```dovetail
package example

trait TextValue =
    function value(self, input: String): Int32

trait Value extends TextValue =
    function value(self, input: Int32): Int32

record Reader = id: Int32

implement Value for Reader =
    function value(self, input: String): Int32 = 10
    function value(self, input: Int32): Int32 = input + 1

function read<R>(reader: R): Int32 where R: Value =
    reader.value("text") + reader.value(20)

function main(): Unit =
    let reader = Reader { id = 0 }
    assert reader.value("text") == 10
    assert reader.value(20) == 21
    assert read(reader) == 31
```

Here `reader.value("text")` selects the inherited `String` method, while
`reader.value(20)` selects the `Int32` method. This also works inside `read`,
where only the `R: Value` bound is known.

The overloads can supply separate default bodies. Eligible interface methods
retain separate dispatch slots, including after conversion to a parent
interface. An implementation missing either required overload is incomplete.
Calls matching more than one overload remain ambiguous; changing only the
return type does not create a valid overload.

---

## Further Reading

[Part 25: Tuple Extension (Advanced)](https://dovetaillang.org/book/tuple-extension.md) applies generic
bounds to tuple shapes and recursive trait implementations. Its
[enclosing-parameter example](https://dovetaillang.org/book/tuple-extension.md#256-enclosing-parameter-bounds)
shows how a method can require a tuple without restricting the whole type.


---

# Part 27: Production Deployment and CI

Source: https://dovetaillang.org/book/production-deployment/


A Dovetail release can be packaged as an OCI container image containing the Linux
runtime and a precompiled application. CI validates the source and publishes the
image; your container platform runs it with the required configuration and storage.
This chapter follows an application project named `api`. Replace that name and
the example registry repository with your own.

## 27.1 Prepare a Reproducible Release

Use a compiler matching `compiler-version` in `Dovetail.toml` and a compatible
standard-library revision. Commit the manifest and `Dovetail.lock`. The selected
compiler release must have matching Linux runtime assets available before image
builds can download them. For compiler development, use the explicit runtime paths
described in the [image guide](https://dovetaillang.org/guides/container-images.md#runtime-releases-and-development-builds).

Add these settings after the application's `[[project]]` entry:

```toml
[project.image]
name = "ghcr.io/acme/api"
platforms = ["linux/amd64", "linux/arm64"]
user = "65532:65532"
expose = ["8080/tcp"]
stop-signal = "SIGTERM"

[project.image.env]
PORT = "8080"

[project.image.wasi]
allow-network = true
inherit-env = true
allow-path = ["/data"]
```

This example assumes the application reads `PORT`, listens on a container-reachable
address such as `0.0.0.0`, and uses `/data` for persistent files. Image configuration
does not implement those application behaviors. Remove grants your application
does not need. Keep passwords, tokens, and private configuration out of image
environment settings and copied files.

Run the initial build to resolve base-image digests:

```sh
dovetail image build -p api
```

Review and commit the resulting `Dovetail.images.lock`. Subsequent release builds
use `--locked` to preserve dependency and base-image selections. It can still
download pinned inputs; `--offline` additionally requires those inputs to be cached.
Update base pins deliberately, then rebuild and validate the new image.

## 27.2 Image Permissions and Deployment Configuration

There are two sets of settings to coordinate:

| Capability | Image setting | Deployment setting |
| --- | --- | --- |
| TCP, UDP, DNS | `allow-network = true` | Container networking, routing, and network policy |
| Incoming connections | Network grant and application listener | Published port or service routing |
| Environment | `inherit-env = true` | Environment values and injected secrets |
| Filesystem | `allow-path = ["/data"]` | Storage mounted at `/data` with appropriate ownership |
| Arguments | Optional image `args` | Container command arguments replace those defaults |

WASI grants default to denied. The builder writes them into
`/app/dovetail-image.json`; there are no startup flags or environment variables
that override them. Change `[project.image.wasi]` and rebuild to change permissions.
Passing `--allow-network` after the image name only passes that string to your
application. An operator could mount a replacement internal JSON file, but this is
a manual replacement of trusted runtime configuration, not a dedicated override
interface.

Allowed filesystem paths refer to the container, not the build or deployment host.
They must exist at startup and are preopened at the same guest path with read/write
permissions. Container OS permissions and read-only mounts still restrict access.
There is no per-path read-only or host:guest mapping syntax in image WASI settings.
Map host storage through the container platform and provision ownership for the
configured user, `65532:65532` in this example.

Network permission enables TCP, UDP, and DNS together; there are no destination
allowlists in image settings. Use your deployment's network controls for narrower
access. Environment inheritance exposes all container environment entries to the
guest. Supplying a volume, environment variable, or port mapping alone cannot grant
guest access.

## 27.3 Configure CI Checks

Copy the bundled [checks workflow](https://github.com/somdoron/dovetail/blob/main/dovetail/ai/assets/dovetail-checks.yml) into
your application's `.github/workflows/dovetail-checks.yml`. Replace
`{{DOVETAIL_VERSION}}` with the exact compiler version from your manifest; this
placeholder is rendered automatically when installed through the AI bundle.
The template downloads the matching Linux executable, verifies its release
checksum, and runs on pull requests and pushes to `main` with `contents: read`.

Its validation sequence runs from the application workspace root:

```sh
dovetail deps fetch --locked
dovetail fmt --check
dovetail check --locked
dovetail test --locked
```

The lockfile must already be committed. If you cache dependency downloads, key
the cache on the compiler version and lockfile, and keep locked checks on cache
hits. Private dependencies also need read credentials available to the job.

These commands use an installed compiler. To validate with a local compiler
checkout, run `cargo run --manifest-path /path/to/compiler/Cargo.toml -- <command>`
from the application workspace instead.

## 27.4 Build and Publish in CI

Copy the bundled [publishing workflow](https://github.com/somdoron/dovetail/blob/main/dovetail/ai/assets/dovetail-publish.yml)
into `.github/workflows/dovetail-publish.yml`. Set the same compiler version,
replace `api`, and configure your repository in `[project.image]`. The template
runs on `v*` tags, grants `packages: write` to the publishing job, and logs into
GHCR with the workflow token. Ensure that token has access to the destination
package. Keep publishing credentials out of untrusted pull-request jobs.

The publishing template builds and pushes; it does not run the checks above.
Insert them before the image build so the tagged revision is validated, or make
publishing depend on a successful check job for that exact revision. Passing checks
on an earlier commit does not validate a later release tag.

The image steps are:

```sh
dovetail image build -p api --locked
# Registry login occurs between these steps in the workflow.
dovetail image push -p api --tag "$GITHUB_SHA"
```

Build creates `build/images/api.oci.tar` for the configured platforms. It requires
no Docker daemon, Dockerfile, or QEMU. Push uploads the existing archive and never
rebuilds it. Login and push must share Docker credential configuration and any
required credential helpers. A separate publishing job must receive the archive
and manifest and perform its own registry login.

Use a commit SHA tag to associate an image with its source, then record the
published registry digest for deployment. Tags can be moved; promote the same
tested digest through staging and production. Retain the archive or published
image and the release's source and lockfiles for diagnosis and rollback.

## 27.5 Run and Verify the Image

After publishing, a Linux container host can run the image. Set `API_IMAGE` to
your published reference, such as `ghcr.io/acme/api@sha256:<actual-digest>`.
Provision `/srv/api-data` on that host with ownership and permissions appropriate
for UID/GID `65532:65532` before starting this example:

```sh
docker run --detach --name api \
  --publish 8080:8080 \
  --mount type=bind,source=/srv/api-data,target=/data \
  --env PORT=8080 \
  "$API_IMAGE"
docker logs api
```

The host path maps into the container path already granted by WASI. The environment
value is visible because the image enabled inheritance. Docker port publishing
and mounts are deployment settings; see the [Docker run reference](https://docs.docker.com/engine/containers/run/)
for their options and image digest syntax. macOS requires a Linux VM or Docker
to execute these Linux images, with emulation when needed for the architecture.

Test the published image with the intended user, environment, storage, and network
before promoting it. Exercise a real application request and a read/write operation
on persistent storage where applicable. Distinguish a missing WASI grant from a
missing directory, incorrect ownership, a read-only mount, or a connection failure.

## 27.6 Operate and Roll Back

Configure resource limits, restart behavior, service routing, and health probes in
your deployment platform. Supply secrets at deployment time, using environment
inheritance or files under an allowed path as appropriate for the application.
Store persistent data outside the container's writable layer and test restoration
from backups.

Expose application health endpoints if your platform needs them. The default
distroless base does not provide a shell for probe scripts; use external probes
or deliberately supply the required executable in a compatible custom base.
Dovetail removes inherited image healthchecks, so configure health monitoring
explicitly. Collect application stdout/stderr through your platform's logging.

`stop-signal` sets container metadata; it does not implement graceful shutdown in
the application. Verify termination behavior and in-flight request handling before
choosing the deployment's shutdown timeout.

Retain the previous successful image digest and deployment configuration. If a
release fails verification, restore those together. Database and file-format
migrations need a compatibility plan: reverting an image does not revert data.
Smoke-test the restored release and verify access to its persistent state.


---

# The Dovetail Programming Language

Source: https://dovetaillang.org/book/


## Table of Contents

---

### [Part 1: Getting Started](https://dovetaillang.org/book/getting-started.md)

- 1.1 Introduction to Dovetail
  - What is Dovetail?
  - Why another language?
  - Design philosophy and principles
  - Target platform (WasmGC)
  - Comparison with other languages
- 1.2 Installation and Setup
  - Prerequisites (Rust toolchain, cargo)
  - Installing with Cargo
  - Installing from source
  - Verifying the installation
- 1.3 Editor Setup
  - VS Code Extension
  - Extension features (syntax highlighting, LSP support)
  - Configuration options
- 1.4 Your First Dovetail Program
  - Creating a project with `dovetail init`
  - The `Dovetail.toml` manifest file
  - Project directory structure
  - Writing "Hello, World!"
  - Building and running

---

### [Part 2: Dovetail Tool Commands](https://dovetaillang.org/book/tool-commands.md)

- 2.1 The Dovetail CLI
- 2.2 Project Structure
- 2.3 Dependency Management
- 2.4 CI and Local Compiler Development

---

### [Part 3: Language Basics](https://dovetaillang.org/book/language-basics.md)

- 3.1 Layout-Sensitive Syntax
- 3.2 Comments and Documentation
- 3.3 Variables and Bindings
- 3.4 Primitive Types
- 3.5 Operators
- 3.6 String Interpolation

---

### [Part 4: Control Flow](https://dovetaillang.org/book/control-flow.md)

- 4.1 If Expressions
- 4.2 Match Expressions
- 4.3 Loops

---

### [Part 5: Functions](https://dovetaillang.org/book/functions.md)

- 5.1 Function Definitions
- 5.2 Positional Arguments and Configuration
- 5.3 Closures and Lambdas
- 5.4 First-Class Function References
- 5.5 Method References
- 5.6 Higher-Order Functions

---

### [Part 6: Type System](https://dovetaillang.org/book/type-system.md)

- 6.1 Type Inference
- 6.2 Records
  - Private construction and `with` updates
- 6.3 Enums (Discriminated Unions)
  - Option Type
  - Result Type
  - Private construction with public pattern matching
- 6.4 Tuples
- 6.5 Newtypes
  - Private construction and inspection
- 6.6 Type Aliases
- 6.7 Lists, Arrays, and Slices
  - Lists and List Literals
  - Accessing and Matching Lists
  - Transforming and Iterating Lists
  - Choosing Between Array and List
  - Shared Array Views and Slicing Syntax
  - Slice Bounds and Constructors
  - Copying, Comparing, and Iterating
  - Slices and Strings
- 6.8 Modules
- 6.9 Extension Methods
- 6.10 The Any Type and Type Casting
  - The Any Type
  - Type Testing with `is`
  - Type Casting with `as`
  - Working with Generic Types and Arrays
- 6.11 Interfaces and Interface Types
  - Declaring and Implementing Interfaces
  - Generic Interfaces and Bounds
  - Intersections and Upcasts
  - Inheritance, Defaults, and `Self`
  - Interface Restrictions and `Any`
  - Choosing a Contract

---

### [Part 7: Generics](https://dovetaillang.org/book/generics.md)

- 7.1 Generic Functions
- 7.2 Generic Types
- 7.3 Constraints

---

### [Part 8: Traits and Implementations](https://dovetaillang.org/book/traits.md)

- 8.1 Defining Traits
- 8.2 Implementing Traits
  - Implementations and private types
- 8.3 Core Traits
  - Identity Equality and Hashing
- 8.4 The Orphan Rule
- 8.5 Trait and Interface Inheritance
- 8.6 Default Methods and Properties
- 8.7 Method Resolution and Explicit Disambiguation

---

### [Part 9: Classes and Object-Oriented Programming](https://dovetaillang.org/book/classes.md)

- 9.1 Class Definitions
- 9.2 Methods
- 9.3 Class Body Fields
- 9.4 Private Constructors
- 9.5 Mutable Fields
- 9.6 Inheritance
- 9.7 Abstract Classes
- 9.8 Sealed Abstract Classes
- 9.9 Generic Classes
- 9.10 Implementing Traits for Classes
- 9.11 Extension Properties
- 9.12 Extension Methods for Classes
- 9.13 Visibility Modifiers
- 9.14 Classes vs Records
- 9.15 Class Identity

---

### [Part 10: Error Handling](https://dovetaillang.org/book/error-handling.md)

- 10.1 No Exceptions
- 10.2 Option Type
- 10.3 Result Type
- 10.4 Railway-Oriented Programming
- 10.5 Panics and Assertions

---

### [Part 11: Packages and Modules](https://dovetaillang.org/book/packages.md)

- 11.1 Package Declaration
- 11.2 Imports
- 11.3 Visibility
  - Type visibility and private construction
- 11.4 No Circular Dependencies
- 11.5 GitHub Dependencies

---

### [Part 12: Async Programming](https://dovetaillang.org/book/async.md)

- 12.1 The Async Type
- 12.2 Async Functions
- 12.3 The `await` Operator
- 12.4 Running Async Code
- 12.5 Parallel Execution

---

### [Part 13: Resource Management](https://dovetaillang.org/book/resources.md)

- 13.1 The `use` Keyword
- 13.2 LIFO Release Order
- 13.3 Release on Failure
- 13.4 Composing Resources
- 13.5 Error Conversion at the Use Site

---

### [Part 14: Streams](https://dovetaillang.org/book/streams.md)

- 14.1 Descriptions and Consumption
- 14.2 Creating a Source
- 14.3 Chunks and Transformations
- 14.4 Concatenation and Flat Mapping
- 14.5 Repeating Effects and Time
- 14.6 Errors and Resource Lifetimes
- 14.7 Merging Concurrent Sources
- 14.8 Running and Folding
- 14.9 Byte Transports

---

### [Part 15: Testing](https://dovetaillang.org/book/testing.md)

- 15.1 Unit Tests
- 15.2 Test Organization
- 15.3 Test Attributes
- 15.4 Running Tests
- 15.5 Testing Best Practices

---

### [Part 16: Macros](https://dovetaillang.org/book/macros.md)

- 16.1 Overview
- 16.2 The `@derive` Attribute
  - Derives and private types
- 16.3 Built-in Derives
- 16.4 Writing Custom Derives (Rhai)

---

### [Part 17: Components](https://dovetaillang.org/book/components.md)

- 17.1 Declaring a Component Dependency
- 17.2 What Gets Generated
- 17.3 Using SQLite
- 17.4 Building and Running
- 17.5 Limits (v1)

---

### [Part 18: Project Structure and Onion Architecture](https://dovetaillang.org/book/project-structure.md)

- 18.1 The Dependency Rule
- 18.2 Three Projects per Bounded Context
  - `primitives` — the value vocabulary
  - `contract` — the public wire surface (data and service contracts)
  - `app` — the context itself
- 18.3 Three Packages Inside `app`
  - The domain package
  - The application package
  - The infrastructure package
- 18.4 What the Compiler Enforces
- 18.5 Variant: the Domain Layer as Its Own Project
- 18.6 Ports and Adapters
  - Repositories
  - The anti-corruption layer
- 18.7 The Composition Root
- 18.8 The Shared Kernel
- 18.9 Talking to Other Bounded Contexts
  - Service contracts, client stubs, and the ACL
  - Integration events
- 18.10 Testing the Layers
- 18.11 Rules at a Glance

---

### [Part 19: The Domain Layer](https://dovetaillang.org/book/ddd.md)

- 19.1 Start With the Types
- 19.2 Make Illegal States Unrepresentable
  - Rules of thumb
  - Errors are types too
  - The compiler as reviewer
  - How far to take it
- 19.3 Value Objects
- 19.4 Entities
  - Make the transition boundary enforceable
- 19.5 Two Styles: Values or Objects
- 19.6 Aggregates
- 19.7 Domain Events
- 19.8 Domain Services
  - Pass the fact, not the port
- 19.9 Factories and Reconstitution
- 19.10 The Anemic Domain Model
- 19.11 Testing the Domain
- 19.12 A Change, End to End

---

### [Part 20: The Application Layer](https://dovetaillang.org/book/application-layer.md)

*(outline)*

- 20.1 What a Use Case Owns
  - The "one change, one transaction, one aggregate" rules
  - Consequences: notification or obligation
  - The sandwich: IO at the edges
  - When the sandwich does not fit: the layered cake
- 20.2 Commands, Queries, and Results
  - Errors from the domain
- 20.3 The Three Triggers
  - Requests
  - Event handlers
  - Jobs
- 20.4 Repositories
- 20.5 Publishing Integration Events
- 20.6 Sagas, Compensation, and Durable Execution
  - Two shapes: backward and forward recovery
  - The problem durable execution solves
  - Dovetail has no durable execution runtime today
- 20.7 Cross-Cutting Concerns
- 20.8 Testing the Application Layer
- 20.9 Worked Example

---

### [Part 21: Strategic Design and Context Mapping](https://dovetaillang.org/book/context-mapping.md)

*(outline)*

- 21.1 Subdomains: Core, Supporting, Generic
- 21.2 Ubiquitous Language and Bounded Contexts
- 21.3 Context Relationship Patterns
- 21.4 Direct Contract Use vs Anticorruption Layer
- 21.5 Integration Events
- 21.6 Drawing and Maintaining the Context Map
- 21.7 Splitting and Merging Contexts

---

### [Part 22: Standard Library Overview](https://dovetaillang.org/book/stdlib.md)

- 22.1 Core Types
- 22.2 Collections
- 22.3 Text Processing
- 22.4 Math
- 22.5 I/O
- 22.6 Networking
- 22.7 Time
- 22.8 JSON
- 22.9 Randomness and Crypto
- 22.10 Streams and SQLite

---

### [Part 23: Best Practices](https://dovetaillang.org/book/best-practices.md)

- 23.1 Code Style
- 23.2 Functional Patterns
- 23.3 Error Handling Patterns
- 23.4 Project Organization

---

### [Part 24: Prefixed String Literals](https://dovetaillang.org/book/prefixed-literals.md)

- 24.1 Why not just build a string?
- 24.2 Syntax
- 24.3 What a literal lowers to
- 24.4 Bounds come from the builder, not the compiler
- 24.5 Writing a builder
- 24.6 Declaring a prefix
- 24.7 Composition instead of in-string control flow

---

### [Part 25: Tuple Extension (Advanced)](https://dovetaillang.org/book/tuple-extension.md)

- 25.1 Extending a Tuple
- 25.2 Extension in Generic Types
- 25.3 Tuple Shape and Accessors
- 25.4 Pair and Recursive Implementations
- 25.5 Parser Composition
- 25.6 Enclosing Parameter Bounds

---

### [Part 26: Advanced Generics](https://dovetaillang.org/book/advanced-generics.md)

- 26.1 Generic Extensions
- 26.2 Class Constraints
- 26.3 Bounds on Enclosing Parameters
- 26.4 Trait and Override Contracts
- 26.5 Variance and Method Bounds
  - Plain Parameters, `out`, and `in`
  - Conditional Bounds on Virtual Methods
- 26.6 Pattern Matching on Generic Types
- 26.7 Generic Trait Defaults
- 26.8 Associated Outputs
- 26.9 Generic Associated Types
  - Generic Resource Helpers
- 26.10 Inherited Overloads

---

### [Part 27: Production Deployment and CI](https://dovetaillang.org/book/production-deployment.md)

- 27.1 Prepare a Reproducible Release
- 27.2 Image Permissions and Deployment Configuration
- 27.3 Configure CI Checks
- 27.4 Build and Publish in CI
- 27.5 Run and Verify the Image
- 27.6 Operate and Roll Back

---

### Appendix

- [A. Grammar Reference](https://dovetaillang.org/reference/grammar.md)
- [B. Operator Precedence Table](https://dovetaillang.org/reference/grammar.md#operator-precedence-table)
- [C. Reserved Keywords](https://dovetaillang.org/reference/grammar.md#keywords)
- [D. Standard Library Quick Reference](https://dovetaillang.org/book/stdlib.md)

[How this book is validated](https://dovetaillang.org/guides/book-validation.md)


---

# Book validation

Source: https://dovetaillang.org/guides/book-validation/


Run from the repository with Python 3.11+ and the Rust toolchain:

```bash
python3 tools/check-book.py
```

CI runs the same check using the local compiler through `cargo run`. It checks local
Markdown links and heading anchors in the README and book, extracts programs marked
**Complete example (checked in CI)**, checks their types, formats them, checks formatting idempotence,
builds and runs them, compares stdout, and runs their declared tests. It also checks
that `init` produces a project that formats, checks, builds, and runs the first
program, including its test selected by name and source file.

Examples use a temporary workspace with this checkout's standard libraries. They do
not require a published standard-library tag, a database server, or network access
at runtime. Cargo dependencies must already be available or downloadable.

Unmarked snippets are explanatory fragments, sometimes deliberately showing errors;
they are not automatically compiled. Documentation comments are not executable doc
tests. External websites, published release downloads, and editor installation are
not checked by this script.

When adding a complete program, place this marker immediately before its Dovetail
code fence (use a unique lowercase name matching the program's package):

```text
<!-- book-example: {"name": "example", "depends": [], "stdout": ""} -->
```

Include `function main(): Unit` and at least one `test`. List required local library
project names in `depends`; `stdout` defaults to empty. Keep assertions deterministic.
The check fails on malformed/duplicate markers, compiler errors, runtime failures,
unexpected output, missing build artifacts, or a run without passing tests.

For a quicker documentation edit:

```bash
python3 tools/check-book.py --links-only
python3 tools/check-book.py --example hello
```


---

# Dovetail Language Grammar

Source: https://dovetaillang.org/reference/grammar/


This document defines the context-free grammar (CFG) of the Dovetail programming language.

## Notation

- `UPPER_CASE` — Terminal symbols (tokens)
- `lower_case` — Non-terminal symbols (grammar rules)
- `|` — Alternation (choice)
- `[ ... ]` — Optional (zero or one)
- `{ ... }` — Repetition (zero or more)
- `( ... )` — Grouping
- `"..."` — Literal keyword or symbol
- `/* ... */` — Comments in grammar

---

## Lexical Grammar

### Whitespace and Comments

```
WHITESPACE      = ( SPACE | TAB )+
NEWLINE         = "\n" | "\r\n"
COMMENT         = "//" { any-char-except-newline }
DOC_COMMENT     = "///" { any-char-except-newline }
```

**Note:** Tabs in indentation are compile errors (spaces only for indentation).

### Keywords

```
FUNCTION    = "function"
LET         = "let"
MUTABLE     = "mutable"
IF          = "if"
THEN        = "then"
ELSE        = "else"
MATCH       = "match"
CASE        = "case"
WITH        = "with"
FOR         = "for"
WHILE       = "while"
IN          = "in"
DO          = "do"
RECORD      = "record"
ENUM        = "enum"
CLASS       = "class"
TRAIT       = "trait"
INTERFACE   = "interface"
IMPLEMENT   = "implement"
EXTENSION   = "extension"
ABSTRACT    = "abstract"
STATIC      = "static"
PUBLIC      = "public"
PRIVATE     = "private"
INTERNAL    = "internal"
IMPORT      = "import"
PACKAGE     = "package"
ASYNC       = "async"
COROUTINE   = "coroutine"
TEST        = "test"
NEWTYPE     = "newtype"
TYPE        = "type"
USE         = "use"
PANIC       = "panic"
ASSERT      = "assert"
EXTENDS     = "extends"
IMPLEMENTS  = "implements"
AND_KW      = "and"         /* for multiple traits: implements A and B */
WHERE       = "where"
AS          = "as"
CONSTRUCTOR = "constructor"
BEGIN_KW    = "begin"       /* explicit begin keyword */
END_KW      = "end"         /* explicit end keyword */
```

### Literals

```
INT_LIT     = digit { digit } [ INT_SUFFIX ]
            | "0x" hex_digit { hex_digit } [ INT_SUFFIX ]
            | "0b" bin_digit { bin_digit } [ INT_SUFFIX ]
            | "0o" oct_digit { oct_digit } [ INT_SUFFIX ]

INT_SUFFIX  = "i8" | "i16" | "i32" | "i64"
            | "u8" | "u16" | "u32" | "u64"

FLOAT_LIT   = digit { digit } "." digit { digit } [ exponent ] [ FLOAT_SUFFIX ]
            | digit { digit } exponent [ FLOAT_SUFFIX ]

FLOAT_SUFFIX = "f32" | "f64"

BIGINT_LIT  = digit { digit } "big"
            | "0x" hex_digit { hex_digit } "big"
            | "0b" bin_digit { bin_digit } "big"
            | "0o" oct_digit { oct_digit } "big"
DECIMAL_LIT = digit { digit } [ "." digit { digit } ] [ exponent ] "dec"

exponent    = ( "e" | "E" ) [ "+" | "-" ] digit { digit }

BOOL_LIT    = "true" | "false"

STRING_LIT  = '"' { string_char | escape_seq | interpolation } '"'
            | '"""' { any_char } '"""'          /* multi-line string */

string_char = any_char_except( '"' | '\' | '$' | newline )

escape_seq  = '\' ( 'n' | 'r' | 't' | '\' | '"' | '$' | '0' )
            | '\u' '{' hex_digit { hex_digit } '}'

interpolation = '$' IDENT
              | '${' expression '}'

/* A prefixed string literal: an identifier immediately followed (no
   whitespace) by a string. The prefix must not be a keyword, and `test` is
   reserved for test declarations. The prefix is an ordinary name in scope,
   declared with `@stringLiteral`, naming the builder type the literal is
   lowered onto; see website/content/book/24-prefixed-literals.md. */
PREFIXED_STRING_LIT
            = IDENT '"' { string_char | escape_seq | prefixed_interpolation } '"'
            | IDENT '"""' { any_char | escape_seq | prefixed_interpolation } '"""'

prefixed_interpolation
            = interpolation                     /* -> builder.value(expr) */
            | '$..' IDENT                       /* -> builder.spread(expr) */
            | '$..{' expression '}'

CHAR_LIT    = "'" ( char | escape_seq ) "'"

digit       = '0'..'9'
hex_digit   = '0'..'9' | 'a'..'f' | 'A'..'F'
bin_digit   = '0' | '1'
oct_digit   = '0'..'7'
```

### Identifiers

```
IDENT       = ident_start { ident_continue }

ident_start    = 'a'..'z' | 'A'..'Z' | '_'
ident_continue = ident_start | '0'..'9'
```

### Operators

```
/* Arithmetic */
PLUS        = "+"
PLUS_PLUS   = "++"          /* concatenation; see the Concat trait */
MINUS       = "-"
STAR        = "*"
SLASH       = "/"
PERCENT     = "%"

/* Comparison */
EQ          = "=="
NE          = "!="
LT          = "<"
LE          = "<="
GT          = ">"
GE          = ">="

/* Logical */
AND         = "&&"
OR          = "||"
NOT         = "!"

/* Bitwise */
BIT_AND     = "&"
BIT_OR      = "|"
BIT_XOR     = "^"
BIT_NOT     = "~"
SHL         = "<<"
SHR         = ">>"

/* Other */
RANGE       = ".."
RANGE_INCL  = "..="
```

### Punctuation

```
LPAREN      = "("
RPAREN      = ")"
LBRACKET    = "["
RBRACKET    = "]"
LBRACKET_PIPE = "[|"    /* opens an array literal */
PIPE_RBRACKET = "|]"    /* closes an array literal; requires adjacency */
LBRACE      = "{"
RBRACE      = "}"
LANGLE      = "<"
RANGLE      = ">"
COMMA       = ","
COLON       = ":"
COLONCOLON  = "::"     /* cons; right-associative */
SEMICOLON   = ";"
ASSIGN      = "="
FAT_ARROW   = "=>"     /* match arms */
ARROW       = "->"     /* lambdas (layout opener) */
DOT         = "."
DOTDOT      = ".."
AT          = "@"
UNDERSCORE  = "_"
QUESTION    = "?"
PIPE        = "|"
```

### Layout Tokens (Virtual)

These tokens are inserted by the layout filter, not present in source:

```
BEGIN       /* Opens an indentation block */
END         /* Closes an indentation block */
SEP         /* Separates expressions in a seq-block */
```

**Note:** The explicit semicolon `;` in source code produces the same `SEP` token.

**Layout Openers:** Tokens that trigger block opening:
- `=` (assignment/definition)
- `then`
- `else`
- `with`
- `->` (lambda arrow)
- `{` (record construction)

---

## Syntactic Grammar

### Program Structure

```
program             = { declaration }

declaration         = package_decl
                    | import_decl
                    | function_decl
                    | record_decl
                    | enum_decl
                    | class_decl
                    | trait_decl
                    | interface_decl
                    | implement_decl
                    | extension_decl
                    | newtype_decl
                    | type_alias_decl
                    | test_decl
```

### Package and Imports

```
package_decl        = "package" package_path

import_decl         = "import" import_path [ "as" IDENT ]

package_path        = IDENT { "." IDENT }

import_path         = IDENT { "." IDENT }
```

### Type Declarations

#### Attributes

Attributes precede the visibility keyword on the declarations that accept them.

```
declaration_attrs   = { derive_attr } [ string_literal_attr ]

/* Applies a derive macro; see website/content/book/16-macros.md.
   Allowed on: record, enum, newtype. */
derive_attr         = "@" "derive" "(" IDENT { "." IDENT } ")"

/* Marks the declared name as the prefix of a prefixed string literal, so
   `IDENT"..."` is available wherever the name is in scope. Takes no argument —
   the prefix IS the name. Allowed on: type alias, record, class.
   See website/content/book/24-prefixed-literals.md. */
string_literal_attr = "@" "stringLiteral"
```

#### Records

```
record_decl         = [ declaration_attrs ] [ doc_comment ] [ visibility ] "record" IDENT [ variant_type_params ] [ "private" ] [ where_clause ] [ "=" record_body ]

record_body         = BEGIN { record_field SEP } record_field [ SEP ] END

record_field        = [ doc_comment ] IDENT ":" type
```

#### Enums

```
enum_decl           = [ doc_comment ] [ visibility ] "enum" IDENT [ variant_type_params ] [ "private" ] [ where_clause ] "=" enum_body

enum_body           = BEGIN { enum_variant SEP } enum_variant [ SEP ] END

enum_variant        = [ doc_comment ] IDENT [ "(" type_list ")" ]

type_list           = type { "," type }

```

#### Classes

```
class_decl          = [ doc_comment ] [ "abstract" ] "class" IDENT [ type_params ]
                      [ constructor_params ]
                      [ "extends" type [ call_args ] ]
                      [ "implements" trait_list ]
                      [ "=" class_body ]

trait_list          = type { "and" type }

constructor_params  = "(" [ constructor_param { "," constructor_param } ] ")"

constructor_param   = [ visibility ] [ "mutable" ] IDENT ":" type [ "=" expression ]

class_body          = BEGIN { class_member SEP } class_member [ SEP ] END
                    | class_member { SEP class_member }

class_member        = field_decl
                    | method_decl
                    | static_method_decl
                    | secondary_constructor

field_decl          = [ doc_comment ] [ visibility ] [ "mutable" ] IDENT ":" type

method_decl         = [ doc_comment ] [ visibility ] "function" IDENT
                      [ type_params ] "(" [ param_list ] ")" [ ":" type ]
                      [ where_clause ] "=" block_expr

static_method_decl  = [ doc_comment ] [ visibility ] "static" "function" IDENT
                      [ type_params ] "(" [ param_list ] ")" [ ":" type ]
                      [ where_clause ] "=" block_expr

secondary_constructor = "constructor" "(" [ param_list ] ")" "=" constructor_call

constructor_call    = IDENT "(" [ arg_list ] ")"
```

#### Traits

```
trait_decl          = [ doc_comment ] "trait" IDENT [ type_params ]
                      [ "extends" named_type { "and" named_type } ]
                      [ "=" trait_body ]

interface_decl      = [ doc_comment ] "interface" IDENT [ type_params ]
                      [ "extends" named_type { "and" named_type } ]  (* interfaces only *)
                      [ "=" trait_body ]

trait_body          = BEGIN { trait_member SEP } trait_member [ SEP ] END

trait_member        = trait_method | trait_property | trait_assoc_type

(* an "=" body on a trait method or property is a default implementation
   (trait-design-appendix §4); implementors may omit such members *)
trait_method        = [ doc_comment ] "function" IDENT [ type_params ]
                      "(" [ param_list ] ")" [ ":" type ] [ where_clause ]
                      [ "=" block_expr ]

trait_assoc_type    = "type" IDENT [ type_params ]
```

#### Trait Implementations

```
implement_decl      = [ doc_comment ] "implement" [ type_params ]
                      trait_type "for" type [ "as" IDENT ] [ where_clause ] [ "=" impl_body ]

impl_body           = BEGIN { impl_member SEP } impl_member [ SEP ] END

impl_member         = method_decl | property_decl | assoc_type_def

assoc_type_def      = "type" IDENT [ type_params ] "=" type
```

#### Extensions

```
extension_decl      = [ doc_comment ] "extension" [ IDENT ] [ type_params ]
                      "for" type [ where_clause ] [ "=" extension_body ]

extension_body      = BEGIN { extension_member SEP } extension_member [ SEP ] END

extension_member    = method_decl | property_decl

property_decl       = [ visibility ] "let" "property" IDENT ":" type "=" expression

/* File-as-extension: if file starts with 'extension for Type',
   the whole file is that extension (no = or body needed) */
```

#### Newtypes

```
newtype_decl        = [ doc_comment ] [ visibility ] "newtype" IDENT [ variant_type_params ] [ "private" ] [ where_clause ] "=" type
```

#### Type Aliases

```
type_alias_decl     = [ string_literal_attr ] [ doc_comment ] [ visibility ] "type" IDENT [ type_params ] "=" type
```

### Functions

```
function_decl       = [ doc_comment ] [ visibility ] [ function_modifier ]
                      "function" IDENT [ type_params ]
                      "(" [ param_list ] ")" [ ":" return_type ]
                      [ where_clause ] "=" block_expr

function_modifier   = "async"
                    | "coroutine"
                    | "async" "coroutine"

return_type         = type
                    | type "," type      /* async return: T, E */

param_list          = param { "," param }

param               = IDENT ":" type [ "=" expression ]

/* Default parameter expressions are planned, not yet implemented. */

where_clause        = "where" constraint { "," constraint }

constraint          = IDENT ":" type_bound { "+" type_bound }

type_bound          = "class" | IDENT [ "<" bound_arguments ">" ]
bound_arguments     = type { "," type } [ "," associated_bindings ] | associated_bindings
associated_bindings = IDENT "=" type { "," IDENT "=" type }
```

### Tests

```
test_decl           = { test_attribute } "test" STRING_LIT [ ":" type ] "=" block_expr

test_attribute      = "@" IDENT [ "(" attr_arg ")" ]

attr_arg            = STRING_LIT | INT_LIT
```

### Type Parameters and Generics

```
type_params         = "<" type_param { "," type_param } ">"

type_param          = IDENT [ ":" type_bound { "+" type_bound } ]

variant_type_params = "<" variant_type_param { "," variant_type_param } ">"

variant_type_param  = [ "out" | "in" ] IDENT [ ":" type_bound { "+" type_bound } ]
```

Note: `variant_type_params` (with optional variance prefix) are used in `record_decl` and `enum_decl`. All other declarations use `type_params`.

### Types

```
type                = tuple_extension_type [ "=>" type ]
                    | "(" [ type { "," type } ] ")" "=>" type

tuple_extension_type = atomic_type { "~" atomic_type }

atomic_type         = named_type
                    | tuple_type
                    | "(" type ")"

named_type          = IDENT { "." IDENT } [ type_args ]

type_args           = "<" type { "," type } ">"

tuple_type          = "(" type "," type { "," type } ")"
                    | "(" named_tuple_field { "," named_tuple_field } ")"

named_tuple_field   = IDENT ":" type

function_type       = "(" [ type { "," type } ] ")" "=>" type
                    | type "=>" type
```

A dotted type name whose root is an in-scope type parameter denotes an associated
type through that parameter's bounds: `P.Output` or `W.Wrapped<T>`. Otherwise,
resolve it as a package-qualified type name. Associated references must match
the declaration's type-parameter count and identify one declaring trait
application. See [Advanced Generics](https://dovetaillang.org/book/advanced-generics.md#268-associated-outputs).

---

## Expressions

### Block Expressions

A block expression contains one or more expressions, with layout determining structure:

```
block_expr          = BEGIN expr_sequence END
                    | "begin" expr_sequence "end"
                    | expression

expr_sequence       = expression { SEP expression }
                    | expression { ";" expression }
```

### Expression Precedence (lowest to highest)

1. `let`, `use`, `if`, `match`, `for`, `while` (binding/control)
2. `||` (logical or)
3. `&&` (logical and)
4. binary `~` (tuple extension; left-associative)
5. `==`, `!=`, `<`, `<=`, `>`, `>=` (comparison)
6. `|` (bitwise or)
7. `^` (bitwise xor)
8. `&` (bitwise and)
9. `<<`, `>>` (shift)
10. `+`, `-`, `++` (additive; `++` is concatenation)
11. `*`, `/`, `%` (multiplicative)
12. unary `!`, `-`, `~` (prefix)
13. postfix (call, field, index, method call, `orReturn`, coroutine operators)
14. primary (literals, identifiers, parenthesized)

### Expression Grammar

```
expression          = let_expr
                    | use_expr
                    | if_expr
                    | match_expr
                    | for_expr
                    | while_expr
                    | assignment_expr
                    | panic_expr
                    | assert_expr
                    | or_expr

/* Bindings */
let_expr            = "let" pattern [ ":" type ] "=" block_expr

use_expr            = "use" IDENT "=" expression

/* Control Flow */
if_expr             = "if" expression "then" block_expr [ "else" block_expr ]

match_expr          = "match" expression "with" match_body

match_body          = BEGIN { match_arm SEP } match_arm [ SEP ] END

match_arm           = "case" pattern [ "if" expression ] "=>" block_expr

for_expr            = "for" pattern "in" expression "do" block_expr

while_expr          = "while" expression "do" block_expr

/* Assignment */
assignment_expr     = postfix_expr "=" expression
                    | or_expr

/* Error Handling */
panic_expr          = "panic" expression

assert_expr         = "assert" expression [ "," expression ]

/* Binary Operators */
or_expr             = and_expr { "||" and_expr }

and_expr            = tuple_extension_expr { "&&" tuple_extension_expr }

tuple_extension_expr = equality_expr { "~" equality_expr }

equality_expr       = comparison_expr { ( "==" | "!=" ) comparison_expr }

comparison_expr     = bitor_expr { ( "<" | "<=" | ">" | ">=" ) bitor_expr }

bitor_expr          = bitxor_expr { "|" bitxor_expr }

bitxor_expr         = bitand_expr { "^" bitand_expr }

bitand_expr         = shift_expr { "&" shift_expr }

shift_expr          = additive_expr { ( "<<" | ">>" ) additive_expr }

additive_expr       = multiplicative_expr { ( "+" | "-" | "++" ) multiplicative_expr }

multiplicative_expr = unary_expr { ( "*" | "/" | "%" ) unary_expr }

/* Unary Operators */
unary_expr          = ( "!" | "-" | "~" | "try" ) unary_expr
                    | postfix_expr

/* Postfix Expressions */
postfix_expr        = primary_expr { postfix_op }

postfix_op          = "." IDENT                          /* field access */
                    | "." IDENT "(" [ arg_list ] ")"     /* method call */
                    | "(" [ arg_list ] ")"               /* function call */
                    | "[" expression "]"                 /* index */
                    | "[|" [ expression ] ".." [ expression ] "|]" /* slice */
                    | "[|" [ expression ] "..=" expression "|]"   /* inclusive slice */
                    | "." "orReturn"                     /* early return */
                    /* coroutine postfix operators like .andWait, .checkpoint */

/* Primary Expressions */
primary_expr        = INT_LIT
                    | BIGINT_LIT
                    | DECIMAL_LIT
                    | FLOAT_LIT
                    | STRING_LIT
                    | PREFIXED_STRING_LIT
                    | BOOL_LIT
                    | IDENT
                    | "(" ")"                            /* unit */
                    | "(" expression ")"                 /* parenthesized */
                    | tuple_expr
                    | array_expr
                    | list_expr
                    | record_construct_expr
                    | with_expr
                    | lambda_expr
                    | closure_expr
                    | async_do_expr

/* Deferred Awaitable Expressions */
async_do_expr       = "async" "do" block_expr

/* Closure Expressions */
closure_expr        = closure_params "=>" block_expr
closure_params      = IDENT
                    | "(" [ closure_param_list ] ")"
closure_param_list  = closure_param { "," closure_param }
closure_param       = IDENT [ ":" type ]

/* Composite Literals */
tuple_expr          = "(" expression "," expression { "," expression } ")"

array_expr          = "[|" [ expression { "," expression } [ "," ] ] "|]"

list_expr           = "[" [ expression { "," expression } [ "," ] ] "]"

/* `::` is right-associative; `a :: b :: []` is the same expression as `[a, b]`. */
cons_expr           = expression "::" expression

record_construct_expr = type_name "{" [ field_init_list ] "}"

field_init_list     = field_init { SEP field_init } [ SEP ]

field_init          = IDENT "=" block_expr

with_expr           = expression "with" "{" field_init_list "}"

/* Lambda */
lambda_expr         = lambda_params "->" block_expr

lambda_params       = IDENT                              /* single param, no parens */
                    | "(" [ lambda_param_list ] ")"

lambda_param_list   = lambda_param { "," lambda_param }

lambda_param        = IDENT [ ":" type ]

/* Arguments */
arg_list            = arg { "," arg }

arg                 = [ IDENT "=" ] expression           /* optional named arg */

/* Positional arguments precede named arguments. Each declared parameter is
   supplied exactly once; names bind against the statically visible declaration.
   Named arguments may be reordered, but eager evaluation follows source order.
   Function values and positional enum/newtype payloads have no argument labels. */

/* Type Name (for constructors) */
type_name           = [ package_path "." ] IDENT [ type_args ]
```

---

## Patterns

```
/* `cons_pattern` is the only infix pattern form. */
pattern             = pattern_atom [ "::" pattern ]

pattern_atom        = wildcard_pattern
                    | literal_pattern
                    | type_annotated_pattern
                    | ident_pattern
                    | constructor_pattern
                    | tuple_pattern
                    | record_pattern
                    | list_pattern

wildcard_pattern    = "_"

literal_pattern     = INT_LIT
                    | FLOAT_LIT
                    | STRING_LIT
                    | BOOL_LIT

type_annotated_pattern = IDENT ":" pattern_type

pattern_type        = named_type
                    | tuple_type
                    | "(" function_type ")"

ident_pattern       = IDENT

constructor_pattern = type_name "(" [ pattern { "," pattern } ] ")"

tuple_pattern       = "(" pattern "," pattern { "," pattern } ")"

record_pattern      = type_name [ type_args ] "{" [ field_pattern { record_pattern_sep field_pattern } [ record_pattern_sep ] ] "}"

record_pattern_sep  = SEP | ","

/* `[]` and `[a, b]` match a `List`, desugaring to `Nil` / nested `Cons`. */
list_pattern        = "[" [ pattern { "," pattern } [ "," ] ] "]"

/* `h :: t` — right-associative, so `a :: b :: rest` nests to the right. */
cons_pattern        = pattern_atom "::" pattern

field_pattern       = IDENT [ "=" pattern ]
```

---

## Visibility

```
visibility          = "public"
                    | "private"
                    | "internal"
```

---

## Documentation Comments

```
doc_comment         = { DOC_COMMENT }
```

---

## Layout Rules Summary

Dovetail is a layout-sensitive language. The layout filter transforms raw tokens by inserting virtual tokens:

### Virtual Tokens

| Token | Meaning |
|-------|---------|
| `BEGIN` | Opens an indentation block |
| `END` | Closes an indentation block |
| `SEP` | Separates expressions in a seq-block |

### Layout Openers

The following tokens trigger block opening:

| Token | Context |
|-------|---------|
| `=` | After function/let/record field definitions |
| `then` | After `if` condition |
| `else` | After `then` block |
| `with` | After record in `with` expression, after `match` |
| `->` | After lambda parameters |
| `=>` | After closure parameters, match arm patterns |

### Block Types

**Seq-block (sequence block):**
- Created when layout opener is followed by a newline, then indented content
- Tokens at **same column** receive `SEP` (allows multiple expressions)
- Tokens at **lesser column** close the block with `END`

**Non-seq-block (single-expression block):**
- Created when layout opener is followed by content on the **same line**
- Tokens at **same or lesser column** close the block with `END`
- No `SEP` tokens are inserted

### Examples

**Seq-block:**
```dovetail
function foo() =
    let x = 5    -- BEGIN, block at column 5
    x + 1        -- SEP (same column)
-- END (outdentation)
```

Token stream: `function foo ( ) = BEGIN let x = 5 SEP x + 1 END`

**Non-seq-block:**
```dovetail
function foo() = 42    -- BEGIN, non-seq-block
function bar() = 7     -- END (closes foo), BEGIN (new for bar)
```

Token stream: `function foo ( ) = BEGIN 42 END function bar ( ) = BEGIN 7 END`

### Special Handling

**If-Then-Else:**
```dovetail
if x > 0 then
    1
else
    -1
```

Token stream: `if x > 0 then BEGIN 1 END else BEGIN -1 END`

**Explicit begin/end:**
```dovetail
function foo() = begin
    let x = 5
    x + 1
end
```

Token stream: `function foo ( ) = begin let x = 5 SEP x + 1 end`

---

## Operator Precedence Table

| Precedence | Operator | Associativity | Description |
|------------|----------|---------------|-------------|
| 1 (lowest) | `\|\|` | Left | Logical OR |
| 2 | `&&` | Left | Logical AND |
| 3 | `==` `!=` | Left | Equality |
| 4 | `<` `<=` `>` `>=` | Left | Comparison |
| 5 | `::` | **Right** | Cons (prepend to a list) |
| 6 | `\|` | Left | Bitwise OR |
| 7 | `^` | Left | Bitwise XOR |
| 8 | `&` | Left | Bitwise AND |
| 9 | `<<` `>>` | Left | Bit shift |
| 10 | `+` `-` `++` | Left | Additive / concatenation |
| 11 | `*` `/` `%` | Left | Multiplicative |
| 12 (highest) | `!` `-` `~` | Right (prefix) | Unary |

`::` sits below `+`/`++` and above comparison, so `x :: xs ++ ys` is
`x :: (xs ++ ys)` and `x :: xs == ys` is `(x :: xs) == ys`.

---

## Complete Example

```dovetail
package example

import http.Request
import http.Response

/// A user record
record User =
    name: String
    age: Int32

/// Extension for User
extension for User =
    function greet(self): String =
        "Hello, ${self.name}!"
    
    static function create(name: String): User =
        User { name = name; age = 0 }

/// A printable trait
trait Printable =
    function print(self): String

/// A base class
class Person(name: String) =
    function greet(self): String = "Hello, I'm ${self.name}"

/// A class with inheritance and trait implementation
class Employee(name: String, title: String) extends Person(name) implements Printable =
    function print(self): String = "${self.name} - ${self.title}"

/// Main entry point
function main(): Unit =
    let user = User.create("Alice")
    let greeting = user.greet()
    print(greeting)

test "user greeting" =
    let user = User { name = "Bob"; age = 30 }
    assert user.greet() == "Hello, Bob!"
```

**Token stream for `main` function:**
```
function main ( ) : Unit = BEGIN
  let user = User . create ( "Alice" ) SEP
  let greeting = user . greet ( ) SEP
  print ( greeting )
END
```

---

## Grammar Ambiguities and Resolutions

### 1. Less-than vs Type Parameter

`<` can be either comparison or start of type arguments:

**Resolution:** In type positions, `<` starts type arguments. In expression positions, use context:
- After type name in constructor: type arguments
- Otherwise: comparison operator

### 2. Arrow Operators

- `->` (arrow) is for lambdas and is a layout opener
- `=>` (fat arrow) is for match arms, closure bodies, and function types; also a layout opener

### 3. Semicolon vs Layout

In record construction, `;` can be used instead of layout-based SEP:
- `Point { x = 1; y = 2 }` (single line with `;`)
- Layout SEP for multi-line

### 4. Bracket after an Expression

A `[` immediately following an expression is always the index operator, never a
list literal: `xs[0]` indexes, `xs [0]` still indexes. A list literal is only
recognised where an expression may *start*.

`[|` following an expression starts a slice: `xs[|i..j|]`, `xs[|i..|]`,
`xs[|..j|]`, `xs[|..|]`, `xs[|i..=j|]`, or `xs[|..=j|]`. The receiver must
be an Array or Slice. `[|` is a single token and a range separator is required,
so `xs[|0|]` is an error. Element indexing remains `xs[0]`; `xs[0..2]` is an
error. Ranges are not first-class expressions. Array literals remain valid
where an expression may start.

### 5. `|]` vs `|` `]`

`|]` requires adjacency, exactly like `++` or `==`. An array literal whose last
element ends in a bitwise-or is written with a space — `[| a | b |]` is a
one-element array holding `a | b`. `[||]` is the empty array, not `[` `||` `]`,
because `[|` is consumed as one token.

---

## Reserved for Future

The following are reserved for potential future use:

- `do` (do-notation)
- `yield` (generators)
- `defer` (deferred execution)
- `macro` (metaprogramming)
- `module` (module system)


---

# Formatting Dovetail

Source: https://dovetaillang.org/guides/formatting/


`dovetail fmt` formats local workspace source files and project tests. Run it
from the workspace root or a subdirectory. It finds the nearest ancestor
`Dovetail.toml`, reads local project and package paths, and includes each
project's `test/` tree. It does not fetch dependencies, read their sources,
generate bindings, or update the lockfile.

Pass explicit `.dove` files to format without a manifest:

```sh
dovetail fmt src/example.dove src/anotherExample.dove
dovetail fmt --check
```

`--check` lists files needing formatting without writing them. Exit codes are
0 for success, 1 for formatting differences in check mode, and 2 for input,
formatting, or filesystem errors. All selected files are parsed and formatted
before writing begins. Each changed file is replaced atomically, retaining its
permissions; replacement is not a transaction across multiple files.

During compiler development, use `cargo run -- fmt` to run the local compiler.

## Canonical style

The formatter chooses indentation, spacing, and wrapping. It preserves one
blank line between statements or declarations, collapsing larger gaps to one.
Other original layout does not influence its choices. There are no style settings or
formatting-disable directives.

- Four spaces per indentation level and a 100-column target.
- A short function body stays after `=`, including after a wrapped signature.
- A multiline conditional chain puts each `else if` and its final `else` on
  a separate line. If any branch body wraps, every branch body starts on a
  new indented line. A whole conditional that fits can remain inline.
- Lists wrap at grammar-supported boundaries. Record fields use semicolons
  inline and layout separators when multiline. Record-pattern fields use
  semicolons inline and between multiline fields, with no trailing semicolon.
  Commas in record patterns are accepted as input and normalized to semicolons.
- A `where` clause stays inline when the whole signature fits within 100
  columns, even if the body is multiline. Otherwise it starts on the next
  line, with wrapped conditions aligned beneath the first condition.
- Continuations indent one level. Long type annotations can wrap after the
  colon. Generic closing angles stay attached to the last type parameter.
- Explicit parentheses are preserved, including redundant grouping and
  parentheses inside interpolations. The formatter can add parentheses where
  wrapping requires them to preserve precedence or block boundaries.
- Comments retain their text and their leading/trailing attachment. Comment
  prose and literal text are not reflowed and can exceed the width target.
- Literal spelling and string text are preserved. Expressions inside string
  interpolation are formatted.
- Imports and declarations retain their order. Generated line breaks use LF,
  and documents end with a newline. Line breaks inside literal text remain data.

Syntax errors leave files unchanged. The formatter reparses its output and
checks the program structure before accepting it. It does not require a
successful typecheck.

## VS Code

The existing Dovetail language server handles **Format Document** using the
same formatter and the current unsaved editor buffer. Configure optional
format-on-save as described in the [extension README](https://github.com/somdoron/dovetail/blob/main/vscode-dovetail/README.md).
Formatting uses the canonical style regardless of editor indentation settings.

## Implementation

The compiler lexer optionally captures original byte ranges, comments, and
interpolation boundaries. The parser optionally records syntax-production
ranges over its token stream. Normal compilation keeps using the same grammar.

The formatter builds documents from this source syntax, retaining spelling
that the compiler AST discards. A small document printer chooses legal line
breaks. The ordinary compiler parser provides structural validation, with
source locations and scope-neutral single-expression block wrappers ignored.
`use` and binding scopes remain significant.

Tests cover representative formatting rules, CLI behavior, LSP buffer handling,
and structural equivalence plus idempotence across local workspace sources.


---

# Container images

Source: https://dovetaillang.org/guides/container-images/


`dovetail image build` compiles configured applications, precompiles each Wasm
component for Linux AMD64 and ARM64, and creates an OCI archive per project.
`dovetail image push` publishes the existing archives using Docker credentials.
Neither command requires a Docker daemon, Dockerfile, or QEMU.

Add image settings after the application's `[[project]]` entry in `Dovetail.toml`:

```toml
[project.image]
name = "ghcr.io/acme/api"
tag = "latest"
```

```sh
dovetail image build -p api
docker login ghcr.io
dovetail image push -p api
```

Omit `-p` to build or push all local projects with image configuration. Imported
projects and libraries without image configuration are not selected. Configured
image projects must have an application entry point.

The default archive is `build/images/<project>.oci.tar`, relative to the workspace
root. Both commands use the same manifest setting when `output` overrides that
path. Push validates all selected archives and destinations before uploading;
it never rebuilds. An archive can be published even if the project's sources or
Git dependencies are unavailable. Run commands from the workspace root.

```sh
dovetail image build -p api --platform linux/amd64
dovetail image push -p api --tag 1.2.3
```

`--tag` replaces only the tag, retaining each project's configured repository.
Push uploads every platform present in the archive, regardless of the current
build platform settings. Two selected projects cannot publish to the same tag.

## Configuration

```toml
[project.image]
name = "ghcr.io/acme/api" # repository only, without tag or digest
tag = "latest"
base = "gcr.io/distroless/cc-debian13:nonroot"
platforms = ["linux/amd64", "linux/arm64"]
output = "build/images/api.oci.tar"
user = "65532:65532"
workdir = "/app"
expose = ["8080/tcp"]
args = []
stop-signal = "SIGTERM"

[project.image.env]
PORT = "8080"

[project.image.labels]
"org.opencontainers.image.title" = "API"

[project.image.annotations]
"org.opencontainers.image.description" = "Application image"

[[project.image.files]]
source = "public"
destination = "/app/public"

[project.image.wasi]
allow-network = true
inherit-env = true
allow-path = ["/data"]
```

Precompilation is mandatory: there is no setting to disable it and no fallback
to startup compilation. Each platform image contains its matching Linux Dovetail
executable and architecture-specific `/app/application.cwasm`.

WASI permissions default to denied, matching `dovetail run`. Setting a container
environment variable, publishing a port, or mounting a directory does not itself
grant the Wasm guest access. Enable network/environment access and list container
paths as needed. Listed paths must exist when the container starts. `expose` is
image metadata; the deployment still supplies port mappings and volume mounts.
Application arguments override image `args` through the container runtime's normal
command arguments. No shell is involved in the generated entrypoint.

These WASI grants are baked into `/app/dovetail-image.json` during image build.
There are no startup flags or environment variables for overriding them: change
`[project.image.wasi]` and rebuild the image. Passing `--allow-network` after the
image name passes an application argument; it does not enable network access.
An operator can manually mount a replacement internal JSON configuration, but
that replaces trusted runtime configuration rather than using a dedicated WASI
override interface.

`allow-network` is one toggle for TCP, UDP, and DNS, without destination allowlists.
`inherit-env` exposes all container environment entries to the guest. `allow-path`
grants read/write access at the same container and guest path, subject to OS
permissions and mount restrictions. There are no per-path read-only grants or
host:guest mappings in these settings; configure mappings and read-only mounts in
the deployment. See [Production Deployment and CI](https://dovetaillang.org/book/production-deployment.md)
for a release workflow and deployment configuration example.

Base layers and their environment and labels are retained; explicitly configured
values override them. Dovetail replaces the process entrypoint, arguments, user,
working directory, ports, and stop signal, and removes an inherited healthcheck.
Additional files are copied from paths relative to the project directory, with
regular files readable as mode 0644 and directories as 0755. Symlinks, paths
outside the project, OCI whiteout names, and overrides of generated runtime files
are rejected. Application resources declared with `resources` remain embedded in
the component and need no extra copy setting.

Additional operating-system packages belong in a custom, already-built base.
A custom base must supply the runtime's compatible GNU/Linux loader and libraries;
Alpine and `scratch` are not suitable for the default dynamically linked binary.
`scratch` is supported only with a self-contained runtime supplied by the user.

## Runtime releases and development builds

The builder downloads matching release executables from the Dovetail GitHub
release `v<compiler-version>`, with assets named:

- `dovetail-x86_64-unknown-linux-gnu` and its `.sha256` file
- `dovetail-aarch64-unknown-linux-gnu` and its `.sha256` file

Downloads are checksum-verified and cached under `.dovetail/images/runtimes`.
Executables must also contain the matching runtime build identity and have the
correct ELF architecture. The runtime identity covers pinned Wasmtime/Cranelift dependency versions,
crate configuration, runtime configuration schema, CLI, and runtime implementation. The image runner checks this
identity and the component digest before deserializing the native artifact.
These checks detect mismatches and corruption; they do not make untrusted native
code safe to execute. The internal `image run` command is only for trusted images.

The `Release binaries` workflow runs when a GitHub release is published (including
prereleases). Its release tag must equal `v<version>` from `dovetail/Cargo.toml`.
It builds and smoke-tests official executables for Linux AMD64/ARM64, macOS
Intel/Apple Silicon, and Windows x64, then attaches each binary and its SHA-256
checksum to that existing release after every platform succeeds. Linux jobs also
execute the packaged container. Pull requests and manual runs validate builds
without uploading to a release.

Additional official assets are named `dovetail-x86_64-apple-darwin`,
`dovetail-aarch64-apple-darwin`, and `dovetail-x86_64-pc-windows-msvc.exe`, each
with a `.sha256` companion. Unix downloads need executable permission
(`chmod +x`) and can be renamed to `dovetail`; rename the Windows binary to
`dovetail.exe`. The Linux executables are also the image runtimes.

The release becomes visible before the build finishes; binaries are available
once the workflow completes successfully. **Until matching Linux assets have
been attached**, development builds need explicit Linux runtime paths:

```toml
[project.image.runtime]
"linux/amd64" = "dist/dovetail-x86_64-unknown-linux-gnu"
"linux/arm64" = "dist/dovetail-aarch64-unknown-linux-gnu"
```

Paths are relative to `Dovetail.toml` (absolute paths also work). Build both Linux
executables and the host compiler from the same checkout and Cargo.lock using
`cargo build --release --locked --bin dovetail`, on the appropriate native hosts
or with a suitable cross toolchain. A Linux host can reuse its running Dovetail
executable for its own architecture. A macOS executable cannot be packaged as a
Linux runtime. Overridden executables remain the caller's trusted input.

### Cross-compiling local runtimes from macOS

With Zig installed, install the Cargo wrapper and Linux Rust targets, then build
both runtimes from the compiler checkout:

```sh
cargo install cargo-zigbuild --locked
rustup target add x86_64-unknown-linux-gnu aarch64-unknown-linux-gnu
cargo zigbuild --release --locked --bin dovetail \
  --target x86_64-unknown-linux-gnu \
  --target aarch64-unknown-linux-gnu
```

Set the runtime overrides to the resulting
`target/x86_64-unknown-linux-gnu/release/dovetail` and
`target/aarch64-unknown-linux-gnu/release/dovetail` executables. Use absolute
paths when the application lives outside the compiler checkout. Building the
image archive requires no Docker; executing its Linux images on macOS requires
a Linux VM or Docker, with emulation for the non-native CPU architecture.

## Reproducibility and offline builds

The first build records platform-specific base-image digests in
`Dovetail.images.lock`; commit that file alongside `Dovetail.lock`. Subsequent
builds reuse those digests even if a base tag moves. To update bases, remove the
relevant entries from `Dovetail.images.lock` and rebuild without `--locked`.

`--locked` requires existing base-image pins and leaves the image lockfile
unchanged. `--offline` requires cached base blobs and runtime binaries (or explicit
runtime paths). Both also retain their normal source-dependency behavior.
`image push --offline` is an error.

Generated layers use stable ordering, modes, ownership, and timestamps. Archives
are written atomically so an unsuccessful build does not truncate an existing
archive. Matching source inputs, runtime, base pins, and image settings produce
repeatable image metadata and layers.

## Registry credentials and GitHub Actions

Dovetail reads `$DOCKER_CONFIG/config.json`, or `~/.docker/config.json` by default.
It respects registry-specific credential helpers, the default credential store,
and inline credentials, including Docker Hub's credential key. Helper programs
must be available on `PATH`. Identity tokens are exchanged for scoped access
tokens. Dovetail neither stores credentials nor includes them in the archive.
Registry traffic uses HTTPS.

After checkout and installing a matching Dovetail release:

```yaml
permissions:
  contents: read
  packages: write

# Inside a job's steps:
steps:
  - run: dovetail image build -p api

  - uses: docker/login-action@v4
    with:
      registry: ghcr.io
      username: ${{ github.actor }}
      password: ${{ secrets.GITHUB_TOKEN }}

  - run: dovetail image push -p api --tag "$GITHUB_SHA"
```

The login and push steps must share the Docker configuration and access to any
configured credential helper. A separate publishing job can download the archive
and `Dovetail.toml`, log in, and run push without compiling the application again.

Archives are standard OCI layouts wrapped in tar, with a `latest` local reference
to the multi-platform index. External tools can publish them too:

```sh
skopeo copy --all oci-archive:build/images/api.oci.tar docker://ghcr.io/acme/api:1.2.3
```