# Rank

> Deterministic configuration language and bootstrap compiler

Complete markdown-oriented Rank documentation bundle for offline reading and LLM ingestion. This file is generated from the Docusaurus docs build and follows the docs ordering used on the website.

## Introduction


Rank is a **declarative, deterministic, finite configuration language** for generating structured outputs such as JSON and YAML.

Write a program that describes your output. Run it. Get the same result every time.

Use Rank when you want typed configuration, reproducible data transforms, provider-backed reads, or explicit mutation plans without hidden runtime state.

If you want installation and a first program, continue to [Getting Started](./getting-started.mdx). If you want the mental model first, read [Concepts](./concepts.mdx). For runnable reference programs, browse [Examples](./examples/index.mdx).

## Quick start

```sh
npm install -g @rank-lang/cli
```

```rank
// src/main.rank
Config = Object { host: string, port: number }

config: Config = {
  host: `api.example.com`,
  port: 8080,
}

pub main = || config
```

```sh
rank src/main.rank
```

```yaml
host: api.example.com
port: 8080
```

Use `--format json` when you want JSON on stdout instead:

```sh
rank src/main.rank --format json
```

## Recommended reading order

1. [Getting Started](./getting-started.mdx) — install, first program, first output
2. [Concepts](./concepts.mdx) — design principles: immutability, graph evaluation, determinism, providers
3. [Language reference](./language/values-and-types.mdx) — types, bindings, functions, imports, stdlib
4. [Output and manifests](./language/output.mdx) — single-document output, `std::Emit<T>`, `Emit::manifest(...)`, and `--file-root`
5. [Errors and diagnostics](./language/errors.mdx) — what fails when, and how to read diagnostics
6. [CLI reference](./cli.mdx) — all commands and flags with examples
7. [Faker provider](./faker-provider.mdx) — generating typed fake data
8. [Dependencies](./dependencies.mdx) — reusable packages from local paths, npm registries, and git
9. [Provider authoring](/docs/provider-authoring) — writing and publishing your own provider

## LLM-friendly docs

For AI assistants, retrieval pipelines, and offline ingestion, the docs build also publishes:

- [llms.txt](https://rank-lang.com/llms.txt) — top-level index of the docs corpus
- [llms-full.txt](https://rank-lang.com/llms-full.txt) — one combined markdown-oriented bundle
- [llms-examples.txt](https://rank-lang.com/llms-examples.txt) — curated runnable examples bundle, including the S3 Logs task-oriented example

For the language specification and implementation internals, see [Spec and plan](./spec-and-plan.mdx).

---

## Getting Started


This guide takes you from zero to a working Rank program. By the end you will have installed the compiler, written a `.rank` file, and produced your first output.

If you want the language model before you install anything, read [Introduction](./intro.mdx) and [Concepts](./concepts.mdx). After this guide, use the [CLI reference](./cli.mdx) and [Examples](./examples/index.mdx) as your working reference.

## Requirements

- Node.js 20 or newer
- npm 10 or newer

## Install

```sh
npm install -g @rank-lang/cli
```

Verify it worked:

```sh
rank --help
```

You should see the command summary printed to your terminal.

## Your first program

Create a new project directory with a manifest and a source file:

```sh
mkdir hello-rank
cd hello-rank
```

Create `rank.toml`:

```toml
manifestVersion = 1

[package]
name = "hello-rank"
version = "0.1.0"
source = "src"
```

Create `src/main.rank`:

```rank
greeting = `Hello, Rank!`

config = {
  message: greeting,
  version: 1,
}

pub main = || config
```

## Check the program

Run the type-checker to validate the program without producing output:

```sh
rank check src/main.rank
```

No output means no errors. If there is a problem, the compiler prints a diagnostic with a source location.

## Produce output

Run the program and emit YAML, which is the default:

```sh
rank src/main.rank
```

You should see:

```yaml
message: Hello, Rank!
version: 1
```

If you prefer JSON, pass `--format json`:

```sh
rank src/main.rank --format json
```

```json
{
  "message": "Hello, Rank!",
  "version": 1
}
```

The primary `rank` command prints YAML for ordinary document results by default and supports `--format json` for JSON output. If you need multiple generated artifacts, return `Emit::manifest(...)` from `pub main` instead. See [Output and manifests](./language/output.mdx).

## Add a type annotation

Rank lets you annotate bindings with explicit types. Add a type to `config` in `src/main.rank`:

```rank
Config = Object {
  message: string,
  version: number,
}

greeting = `Hello, Rank!`

config: Config = {
  message: greeting,
  version: 1,
}

pub main = || config
```

Run `rank check src/main.rank` again — the compiler now validates that `config` matches the `Config` type.

Try introducing a type error:

```rank
config: Config = {
  message: greeting,
  version: `not a number`,
}
```

```sh
rank check src/main.rank
```

The compiler reports the mismatch with a source location before any output is produced.

## Read an environment variable

Rank reads environment variables through the `Env<T> {}` built-in. Update `src/main.rank`:

```rank
SysEnv = Object {
  APP_ENV: string,
  ...: string,
}

env = Env<SysEnv> {}

config = {
  message: `Hello, Rank!`,
  version: 1,
  env: env.APP_ENV,
}

pub main = || config
```

Run it with the variable set:

```sh
APP_ENV=production rank src/main.rank
```

```yaml
message: Hello, Rank!
version: 1
env: production
```

The same command also accepts `--format json` when you need machine-readable stdout.

If `APP_ENV` is not set, the compiler reports a missing environment variable diagnostic.

## What's next

- [Concepts](./concepts.mdx) — understand the design principles behind Rank
- [Language reference](./language/values-and-types.mdx) — bindings, types, functions, imports, and the standard library
- [Output and manifests](./language/output.mdx) — single-document output and multi-file generation
- [Errors and diagnostics](./language/errors.mdx) — common failure modes and how to interpret them
- [CLI reference](./cli.mdx) — all commands and flags
- [Faker provider](./faker-provider.mdx) — generate typed fake data

---

## Concepts


Rank is a **declarative, deterministic, finite configuration language** for generating structured outputs and explicit emit descriptors.

Understanding what Rank deliberately *is not* is just as important as understanding what it is.

Read this page when you are deciding whether Rank fits typed configuration, provider-backed workflows, or HTTP handlers with explicit external inputs. For runnable programs, browse [Examples](./examples/index.mdx). For commands, see the [CLI reference](./cli.mdx). For server and provider surfaces, jump to [HTTP Server](./server.mdx), [AWS Provider](./aws-provider.mdx), [Faker Provider](./faker-provider.mdx), and [Provider authoring](/docs/provider-authoring).

## What Rank is

Rank is a functional, graph-evaluated language for producing structured data and explicit emit descriptors. You write a program that describes an output — a configuration file, a dataset, a manifest, or a commit-aware result — and Rank evaluates it. When a program returns a top-level `std::Emit<T>` descriptor, the host decides how to realize it.

Rank is well-suited for:

- generating configuration files (Kubernetes manifests, Terraform inputs, CI pipelines)
- producing typed, validated JSON or YAML from a structured description
- transforming and combining data from external sources in a reproducible way
- modeling explicit provider-backed writes without hiding when commit occurs
- enforcing invariants (uniqueness, port ranges, cross-field constraints) at compile time

## What Rank is not

Rank is **not a general-purpose programming language**. The following are intentional non-goals:

| Not supported | Why |
|---|---|
| In-place mutation or mutable state | Values are assigned once and never change; provider-backed writes use explicit `std::Mutation` plans instead |
| Recursion | All computation must terminate statically |
| Unbounded loops | `while`-style control flow does not exist |
| Hidden side effects | Every external read and provider write is explicit, declared, and host-admitted |
| Turing-completeness | The compiler can fully analyze any valid program |

Rank is not a general-purpose application runtime. It produces *data* — configuration files, datasets, manifests, and explicit emit descriptors — that other systems consume. The `rank serve` command is the main exception: it provides a lightweight HTTP server for programs whose serve-time `pub main` accepts `Runtime::ExecutionContext<Routes>` and returns an `HTTP::Response`, but the handler logic itself is still a declarative Rank function evaluated per request.

## Core concepts

### Immutable bindings

Every name in a Rank program is assigned exactly once. There is no reassignment, no mutation, and no mutable state:

```rank
host = `api.example.com`
port = 8080

// host and port cannot be changed after this point
```

This makes the value of any binding trivially traceable — it is always the expression on the right-hand side of its declaration.

### Graph evaluation

Rank builds a **directed acyclic graph** (DAG) of bindings before evaluating anything. Nodes are bindings and expressions; edges are data dependencies. The compiler evaluates nodes in topological order — each value is computed exactly once, after all its inputs are ready.

Cycles are compile errors. If `a` depends on `b` and `b` depends on `a`, the program is rejected before evaluation begins.

```rank
width = 1920
height = 1080
aspect_ratio = width / height    // evaluated after width and height
```

```mermaid
graph LR
  width["width = 1920"]
  height["height = 1080"]
  aspect_ratio["aspect_ratio = width / height"]

  width --> aspect_ratio
  height --> aspect_ratio
```

Arrows point from dependency to dependent. `width` and `height` have no incoming edges — they are evaluated first. `aspect_ratio` is evaluated last, once both inputs are ready.

### Determinism

Given the same source, the same declared external inputs, and the same compiler version, ordinary Rank evaluation and emit descriptor construction always produce the same values. There is no ambient randomness, no hidden clock access, and no implicit network IO during ordinary compute.

When a host realizes `Mutation::commit(...)`, possible write outcomes are still explicit in typed commit results rather than hidden inside ordinary evaluation.

This makes Rank programs safe to commit, cache, and reproduce.

### Explicit external inputs

Rank can read from the outside world, but every external dependency must be explicitly declared. The supported external input forms are:

- **Environment variables** — `Env<T> {}` reads named variables from the host environment once per compilation
- **Files** — `File::Read<T> { path, format }` reads a local file at a statically-known path, including `dotenv` files with the same flat text `Decode<...>` support as `Env<T> {}`
- **HTTP fetches** — `HTTP::Fetch<T> { ... }` makes a network request with explicit cache/pin semantics
- **Providers** — out-of-process extensions registered in `rank.toml` that expose typed reads and writes through a namespace

Because every external dependency is declared and every provider write crosses an explicit commit boundary, the compiler can list all dependencies (`rank deps`), and repeated runs with cached inputs remain reproducible.

### Data providers

Providers are out-of-process extensions that expose typed operations to Rank programs. They can expose pure helper functions, backend-style reads, and explicit mutation exports. `@rank-lang/plugin-faker` and `@rank-lang/plugin-aws` are first-party examples.

Providers are the *only* way to introduce capabilities beyond pure data transformation — and even then, the capability (`network`, for example) must be explicitly declared in the provider manifest and admitted by the host.

Providers are not plugins to the compiler. They are separate processes that the compiler spawns and communicates with over a JSON-line stdio protocol. A Rank program that uses a provider is still fully type-checked and deterministic with respect to its declared inputs.

### Explicit mutation boundary

Rank does support external writes, but not as mutable state inside the language.

- ordinary bindings stay immutable
- provider-backed writes are declared as `Mutation::Effect<T>` obligations
- fulfilled mutation values may feed later mutation payloads, but they stay commit-local
- actual external IO happens only when a host realizes a top-level `Mutation::commit(...)`

That split is what lets Rank support writes without turning ordinary evaluation into imperative execution. See [Mutations](./language/mutations.mdx) for the full lifecycle.

### The type system

Rank has a structural type system. Types describe the *shape* of values, not their identity. Object types are closed by default:

```rank
Config = Object {
  host: string,
  port: number,
}
```

The language supports generics, including declaration-site constraints (`K extends keyof T`) and trailing defaults (`Box<T = string>`), plus type unions (`A | B`), type intersections (`A & B`), optional fields (`field?: T`), and open object types (`...: T` for additional fields). Type aliases use leading-uppercase names.

Structured text is a first-class part of the language too: `parse` template types let programs treat string formats as types, and the same `parse` / pattern syntax reappears in `match` expressions and route matching instead of pushing string handling out into ad-hoc helper code.

### Compile-time constraints

Annotations attach compile-time invariants to declarations and to ordinary object-type fields:

```rank
@constraint(cond: |self| self >= 1 && self <= 65535)
api_port = 8080

@unique(group: ports)
api_port = 8080

@unique(group: ports)
db_port = 5432

ServiceConfig = Object {
  @constraint(cond: |self| self >= 1)
  replicas: number,
  @sensitive
  token?: string,
}
```

Constraint failures are compile errors, not runtime errors. Declaration annotations validate a specific binding; field annotations travel with the type and are enforced wherever that type is checked.

### Output model

For ordinary command-line evaluation, the entrypoint is the exported `pub main` function. Its return value is what the host emits or realizes.

Rank can emit:

- **One ordinary document** — bare `rank <entry>` prints the evaluated document result as YAML by default, or as JSON with `--format json`
- **A multi-file manifest descriptor** — `Emit::manifest(...)` returns `std::Emit<T>` for later materialization
- **A commit-aware descriptor** — `Mutation::commit(...)` returns `std::Emit<T>` with typed write outcomes projected into ordinary output

Emitted output preserves evaluated field order. There is no implicit reordering.

See [Output and manifests](./language/output.mdx) for the `std::Emit<T>` manifest workflow and `--file-root` behavior, and [Mutations](./language/mutations.mdx) for commit-aware output.

## How Rank relates to other tools

| Tool | Relationship |
|---|---|
| Jsonnet | Similar scope; Rank adds a structural type system and explicit external inputs |
| CUE | Similar type model; Rank is evaluation-first rather than constraint-unification-first |
| Dhall | Similar determinism goal; Rank is array-oriented and supports providers |
| Helm / Kustomize | Rank replaces the templating layer with a typed, validated language |
| General scripting (Python, Bash) | Rank handles the data-generation step; scripting handles deployment and orchestration |

---

## Bindings and functions


## Bindings

A binding assigns a name to a value. Bindings are immutable — every name is assigned exactly once:

```rank
host = `api.example.com`
port = 8080
config = { host, port }
```

Bindings may carry an explicit type annotation:

```rank
port: number = 8080
```

Bindings can reference other bindings freely. The compiler builds a dependency graph and evaluates everything in the correct order:

```rank
base_port = 3000
api_port = base_port + 1
db_port = base_port + 2
```

```mermaid
graph LR
  base_port["base_port = 3000"]
  api_port["api_port = base_port + 1"]
  db_port["db_port = base_port + 2"]

  base_port --> api_port
  base_port --> db_port
```

## Entrypoint

Every Rank program exports a zero-argument function named `pub main`. Its return value is what gets emitted:

```rank
config = {
  host: `localhost`,
  port: 8080,
}

pub main = || config
```

`||` is the zero-argument function syntax. `pub` marks the binding as exported.

## Functions

Functions are first-class values. They can be bound to names, passed as arguments, and returned:

```rank
increment = |x| x + 1
add = |left, right| left + right
```

Functions with a block body use `return` to yield their result:

```rank
clamp = |value, min, max| {
  clamped = value < min ? min : (value > max ? max : value)
  return clamped
}
```

Typed block-bodied functions declare parameter and return types:

```rank
normalize = |port: number, max: number| -> number {
  ratio = port / max
  return ratio
}
```

Functions are compile-time values. They are used during evaluation but cannot appear in the final emitted output.

## Destructuring

Object fields can be destructured directly into bindings:

```rank
response = { status: 200, body: `ok` }
{ status, body } = response
```

This is shallow sugar: each identifier reads the same-named field from the source object.

Annotations can also attach to a destructuring declaration, but their behavior depends on the annotation:

- `@constraint` receives the full source object as `self`
- `@unique` registers each extracted field independently
- `@sensitive` marks every extracted binding as sensitive

For example, a destructuring constraint can validate a relationship between fields on the source object:

```rank
@constraint(cond: |self| self.api_port != self.db_port)
{ api_port, db_port } = config
```

## Annotations

At declaration level, annotations attach compile-time invariants or diagnostic metadata to the immediately following declaration.

`@constraint` runs a boolean check at compile time:

```rank
@constraint(cond: |self| self >= 1 && self <= 65535)
port = 8080
```

`@unique` enforces uniqueness across all bindings in the same named group within the program:

```rank
@unique(group: ports)
api_port = 8080

@unique(group: ports)
db_port = 5432

@unique(group: ports)
metrics_port = 8080   // compile error: 8080 is already in the `ports` group
```

On a destructuring declaration, `@unique` checks each extracted field independently against the group.

`@sensitive` marks a binding as redacted in diagnostics and traces:

```rank
@sensitive
secret_key = env.SECRET_KEY
```

On a destructuring declaration, all extracted bindings become sensitive:

```rank
credentials = {
  access_key_id: `AKIA...`,
  secret_access_key: `...`,
}

@sensitive
{ access_key_id, secret_access_key } = credentials
```

Ordinary object-type fields can also carry field-level `@constraint`, `@unique`, and `@sensitive` annotations:

```rank
ServiceConfig = Object {
  @unique(group: service_ids)
  id: string,
  @constraint(cond: |self| self >= 1 && self <= 65535)
  port: number,
  @sensitive
  token?: string,
}
```

Field annotations differ from declaration annotations:

- `self` inside a field-level `@constraint` is the field value, not the containing object.
- They are valid on ordinary fields in `Object { ... }` and refinement bodies.
- They are enforced whenever a concrete value is checked against the annotated type.
- Utility-type views such as `Pick`, `Partial`, and `Required` preserve them when the field survives.
- Mapped bodies and rest fields do not accept field annotations in the current language surface.

Doc comments use stacked `///` lines and attach to the immediately following declaration:

```rank
/// The port the HTTP API listens on.
/// Must be in the unprivileged range.
@constraint(cond: |self| self >= 1024 && self <= 65535)
api_port = 8080
```

Doc comments are preserved in YAML and JSONC output.

## Operators

### Arithmetic

`+`, `-`, `*`, `/`, `%` operate on numbers. `+` also concatenates strings:

```rank
sum = 1 + 2
label = `port-` + `8080`
```

### Comparison and equality

`<`, `<=`, `>`, `>=` operate on numbers. `==` and `!=` use deep structural equality:

```rank
same = { a: 1 } == { a: 1 }   // true
```

Comparison and equality operators are non-chainable.

### Boolean

`&&`, `||`, `!` are boolean operators:

```rank
valid = port >= 1024 && port <= 65535
```

### Null defaulting

`??` returns the left side unless it is `null`, then evaluates and returns the right:

```rank
value = maybe_null ?? `default`
```

### Ternary

`condition ? then_value : else_value` — evaluates only the selected branch:

```rank
label = is_prod ? `production` : `development`
```

### Object and list composition

`with` performs a deep recursive merge. Right-hand fields win on conflict:

```rank
base = { host: `localhost`, port: 80, tls: false }
override = base with { port: 443, tls: true }
// { host: `localhost`, port: 443, tls: true }
```

`++` composes two lists or two disjoint objects:

```rank
all_ports = [80, 443] ++ [8080, 8443]
merged = { a: 1 } ++ { b: 2 }   // keys must not overlap
```

### Pipeline

`|>` passes the left value as the first argument to the right function. Useful for chaining transformations:

```rank
use std::collections::{ map, filter }

result = [1, 2, 3, 4, 5]
  |> filter(|x| x > 2)
  |> map(|x| x * 10)
// [30, 40, 50]
```

## Pattern matching

`match` is Rank's general pattern-matching form. It is how the language branches on literals, types, object shapes, and structured strings.

### Literal and type patterns

`match` dispatches on a value using literal patterns and type patterns:

```rank
Mode = `dev` | `prod`
mode: Mode = `dev`

label = match mode {
  `dev` => `development`,
  `prod` => `production`,
}
```

Named type patterns narrow the scrutinee type inside the arm:

```rank
describe = |value: string | number| match value {
  string => `it is a string`,
  number => `it is a number`,
  _ => `unknown`,
}
```

### Object patterns

Named type arms can also destructure object-shaped variants and bind fields for that arm only:

```rank
Circle = Object {
  radius: number,
  color: string,
}

Square = Object {
  side: number,
  color?: string,
}

Shape = Circle | Square

measure = |shape: Shape| -> number {
  return match shape {
    Circle { radius } => radius,
    Square { side } => side,
  }
}
```

### `parse` string patterns

Structured string patterns can bind pieces of a string with `parse` templates:

```rank
sumVersionParts = |version_string: string| -> number {
  return match version_string {
    parse`{major:number}-{minor:number}-{patch:number}` => major + minor + patch,
    _ => 0,
  }
}
```

This is the pattern-matching sibling of `parse` template types. In a type alias, `parse` constrains which strings are valid. In a `match` arm, the same syntax binds decoded captures like `major`, `minor`, and `patch`.

The same surface works for irregular structured text too, not just version strings:

```rank
readAccessStatus = |line: string| -> string | null {
  return match line {
    parse`{clientIp:string} - {remoteUser:string} [{timestamp:string}] "{method:string} {target:string} HTTP/{protocol:string}" {status:string} {bytesSent:string} "{referrer:string}" "{userAgent:string}"` => status,
    _ => null,
  }
}
```

See the [S3 Logs example](../examples/s3-logs.mdx) for a complete server that parses nginx access lines this way.

### Scope and exhaustiveness

Bindings introduced by destructuring or `parse` patterns exist only inside the arm where they are declared.

`_` is the wildcard arm. Match is exhaustive — if the compiler can prove the arms do not cover all possible values, it reports an error, and if it cannot prove exhaustiveness you should include `_`.

Pattern matching is not an isolated feature. The same structured-text and matching ideas also show up in route definitions such as ``path: match`/users/{id:UserId}``` and in `parse` template types used elsewhere in the language.

## Automatic lifting

When a function is applied to a list or object, Rank automatically distributes the call across the elements:

```rank
increment = |x: number| x + 1

result = increment([1, 2, 3])   // [2, 3, 4]
keyed  = increment({ a: 1, b: 2 })   // { a: 2, b: 3 }
```

When both arguments are lists of the same length, the function is applied element-wise (zipped):

```rank
add = |left: number, right: number| left + right
sums = add([1, 2, 3], [10, 20, 30])   // [11, 22, 33]
```

Lifting is shape-based and applies only to lists and objects. `null` is not a collection shape — functions that receive `null` through lifting must handle it explicitly.

---

## Errors and diagnostics


Rank prefers explicit diagnostics over coercions, silent fallbacks, or partial output. Most failures fit into a small set of stages.

## Where errors happen

### Parse and resolution

These failures happen before type checking:

- syntax errors
- unresolved names
- invalid imports
- module cycles

### Type checking and annotations

These failures happen once the compiler can analyze program structure:

- type mismatches
- invalid collection or object shapes
- bad `@constraint`, `@unique`, or `@sensitive` usage
- invariant violations such as duplicate `@unique` values

Use `rank check <entry>` to catch this entire class without evaluating external inputs.

### Evaluation and external inputs

These failures happen only when the program is actually evaluated:

- missing or invalid `Env<T>` inputs
- `HTTP::Fetch` cache or schema mismatches
- provider invocation failures
- invalid `Emit::manifest(...)` entries
- path normalization and path escape errors

Use bare `rank <entry>` when you need to exercise these runtime-like evaluation steps.

### Host workflow errors

Some errors are about how the CLI command is used rather than the Rank value itself:

- `--file-root` used with a non-manifest result
- serve-only entrypoints used with the wrong command
- output materialization paths that resolve outside the chosen root

## Common categories

- **Type and shape errors** — the value does not match its declared or inferred type.
- **Annotation errors** — an annotation is unknown, misplaced, malformed, or its invariant evaluates to false.
- **External input errors** — environment variables, HTTP responses, files, or providers do not satisfy the declared schema.
- **Output manifest errors** — duplicate paths, unsupported formats, or mismatched payloads such as non-string `text` values in `Emit::manifest(...)` entries.
- **Path errors** — invalid relative paths, upward traversal, or boundary violations while applying a manifest.

## Sensitive values

Use `@sensitive` on bindings that should be redacted in diagnostics:

```rank
@sensitive
api_key = Env<Object { API_KEY: string, ...: string }> {}.API_KEY
```

When a diagnostic renders that binding, Rank shows `<sensitive>` instead of the real value.

## Practical workflow

1. Run `rank check <entry>` first for syntax, import, type, and annotation problems.
2. Run `rank <entry>` when you need to validate environment inputs, providers, HTTP fetches, or output manifests.
3. Use `rank test <path>` when you want to pin either expected output or expected diagnostics in a repeatable suite.

## Related pages

- See [Bindings and functions](./bindings.mdx) for `@constraint`, `@unique`, and `@sensitive`.
- See [External inputs](./external-inputs.mdx) for `Env`, `HTTP::Fetch`, and `File::Read` behavior.
- See [Output and manifests](./output.mdx) for manifest-specific errors.

---

## External inputs


Rank can read from the outside world, but every external dependency must be explicitly declared. The compiler refuses to perform ambient IO — every network request, file read, or environment lookup is part of the dependency graph and can be listed with `rank deps`.

External inputs are **source nodes** in the DAG — they have no incoming edges. Bindings that read from them depend on those nodes like any other:

```mermaid
graph LR
  env["Env&lt;AppEnv&gt; {}"]:::external
  file["File::Read&lt;Items&gt; {}"]:::external
  http["HTTP::Fetch&lt;Response&gt; {}"]:::external

  port["port = env.PORT ?? '5432'"]
  total["total = items |> ..."]
  users["users = http.users"]

  main["pub main"]

  env --> port
  file --> total
  http --> users

  port --> main
  total --> main
  users --> main

  classDef external fill:#e8f4fd,stroke:#2196f3
```

## Environment variables

`Env<T> {}` reads named environment variables from the host. The type parameter is an object type describing which variables to read:

```rank
AppEnv = Object {
  DATABASE_URL: string,
  PORT?: string,
  DEBUG?: string,
  ...: string,
}

env = Env<AppEnv> {}

port = env.PORT ?? `5432`
```

The environment is snapshotted exactly once per compilation. Only fields declared in the schema type are materialized into the resulting value. The `...: string` rest type allows additional keys to exist in the environment without being read.

Optional fields (`field?: string`) become `null` when the variable is absent. Required fields cause a compile error if absent.

When the host value is text but the rest of the program wants a non-string type, decode it at the boundary:

```rank
use std::Decode

AppEnv = Object {
  PORT?: Decode<8080 | 8443>,
  DEBUG?: Decode<bool>,
  ...: string,
}

env = Env<AppEnv> {}
port = env.PORT ?? 8080
debug = env.DEBUG ?? false
```

This keeps parsing at the edge instead of matching on raw strings later. See [Standard library](./stdlib#stddecode).

## File reads

`File::Read<T> { path, format }` reads a structured file at a relative path:

```rank
use std::File
use std::Path
use std::collections::{ map }
use std::list::{ reduce }

Items = [Object { id: string, name: string, count: number }]

response = File::Read<Items> {
  path: Path::join([`data`, `items.json`]),
  format: `json`,
}

items = response.body
total = items |> map(|item| item.count) |> reduce(0, |acc, n| acc + n)
```

The result is an object with two fields:

| Field | Type | Description |
|---|---|---|
| `body` | `T` | Parsed, type-checked file contents |
| `ctx` | `Object { path: string, format: string }` | Metadata about the read |

Supported formats:

| Format | Decoded as |
|---|---|
| `json` | Ordinary Rank lists and objects |
| `yaml` | Ordinary Rank lists and objects |
| `csv` | List of header-keyed objects with string values |
| `dotenv` | Flat string-keyed object, with the same field-local and schema-wide `Decode<...>` support as `Env<T> {}` |

`path` must be a `Path::RelativePath` value. It resolves relative to the containing module file. Absolute paths and paths that escape upward (`../`) are rejected. The path must be statically evaluable — it cannot depend on a runtime value.

For `.env`-style files, keep parsing at the boundary just like `Env<T> {}`:

```rank
use std::Decode
use std::File
use std::Path

Config = Object {
  APP_ENV: `dev` | `prod`,
  PORT?: Decode<8080 | 9000>,
  DEBUG?: Decode<bool>,
  ...: string,
}

config = File::Read<Config> {
  path: Path::join([`.env`]),
  format: `dotenv`,
}

port = config.body.PORT ?? 8080
debug = config.body.DEBUG ?? false
```

Dotenv decoding stays intentionally narrow in v0:

- the file decodes as a flat string-keyed object
- field-local `Decode` and schema-wide `File::Read<Decode<T>>` are supported for the same scalar targets as `Env<T> {}`
- one dotenv entry does not decode into a nested list or object value
- interpolation and shell-style evaluation are not supported

## HTTP fetches

`HTTP::Fetch<T> { ... }` makes a network request and decodes the response body against `T`:

```rank
use std::HTTP

Response = Object {
  users: [Object { id: number, name: string }],
}

response = HTTP::Fetch<Response> {
  url: `https://api.example.com/users`,
  method: `GET`,
  headers: {
    Accept: `application/json`,
  },
  cacheKey: `users-v1`,
}

users = response.body.users
status = response.ctx.status
```

### Request fields

| Field | Required | Description |
|---|---|---|
| `url` | yes | Request URL (must be a string literal or statically evaluable) |
| `method` | yes | HTTP method: `GET`, `POST`, etc. |
| `headers` | no | Object of header name → value strings |
| `cacheKey` | yes | Stable string key used to replay the response deterministically |

### Result shape

The result is an object with two fields:

| Field | Type | Description |
|---|---|---|
| `body` | `T` | Parsed, type-checked response body |
| `ctx` | see below | Request metadata |

`ctx` fields:

| Field | Type | Description |
|---|---|---|
| `status` | `number` | HTTP status code |
| `cacheKey` | `string` | The `cacheKey` value from the request |
| `headers` | `Object { ...: string }` | Response headers |

### HTTP snapshot caching

The `cacheKey` field is required. It makes fetches deterministic: two runs with the same `cacheKey` and a snapshot file replay identically without a live network request.

Save a snapshot after a live run:

```sh
rank src/main.rank --write-http-cache snapshots.json
```

Replay from the snapshot on subsequent runs:

```sh
rank src/main.rank --http-cache snapshots.json
```

The snapshot cache is a `rank/http-cache` JSON document keyed by each fetch's `cacheKey`. Committing the snapshot to source control makes CI runs fully reproducible without network access.

## Providers

Providers are out-of-process extensions registered in `rank.toml`. They expose typed functions under a namespace and can come from a local path or an npm package. Pure reusable library code belongs under `[dependencies]` instead, which may be local, npm-backed, or git-backed. See the [Provider guide](../faker-provider.mdx), [Dependencies](../dependencies.mdx), and [Provider authoring guide](/docs/provider-authoring) for full details.

```rank
use faker::{ Generate, UUID }

spec = { id: UUID {} }

pub main = || Generate<Object { id: string }> {
  spec,
  seed: 42,
}
```

### Provider capabilities

Providers that need network access or other privileged capabilities must declare them in their manifest. At the call site, the capability must be explicitly opted into:

```sh
rank src/main.rank --allow-provider-capability network
```

This makes capability use auditable — a CI script that does not pass `--allow-provider-capability` will fail if the program unexpectedly depends on a network-capable provider.

---

## Modules and imports


Rank programs are organized into modules. Each `.rank` source file is a module. Modules import from four distinct namespace sources, and project-local code may also use contextual relative anchors for nearby modules.

## Namespace sources

| Prefix | Source |
|---|---|
| `std::` | Official standard library modules and bundled providers |
| `root::` | The current project's source tree |
| `package_name::` | Installed third-party packages exposing pure Rank modules from local paths, npm registries, or git snapshots |
| `provider_name::` | Registered providers from local paths or npm packages, plus any Rank source modules they ship |

## Import syntax

Named imports bring specific bindings into scope:

```rank
use std::collections::{ map, filter, reduce }
use std::object::{ mapValues, keys }
use root::helpers::{ make_url }
use super::types::{ Config }
use self::internal::{ normalize }
```

Wildcard imports bring all exported bindings into scope:

```rank
use std::collections::*
use root::util::*
```

Named imports are preferred when only a few bindings are needed. Wildcards are useful for namespaces you use heavily.

For project-local modules:

- `root::...` is the canonical absolute import form
- `self::...` resolves from the current module namespace
- `super::...` resolves from the parent namespace and may be chained

`self::` and `super::` are contextual anchors only when they appear as the leading segment of a qualified module path.

## Standard library imports

```rank
use std::collections::{ map, filter, flatMap, find, any, all, count }
use std::collections::{ zip, reduce, groupBy, keyBy, sort, sortBy }
use std::list::{ range, flatten, slice, transpose }
use std::object::{ mapValues, keys, values, entries, fromEntries }
use std::Regex::{ matches, search, replace, captures }
use std::Time::{ parse, format, add, diff, minutes }
use std::Path::{ join, from, toString }
use std::Emit
use std::Rand::{ seed, derive, int }
```

See the [Standard library](./stdlib.mdx) page for full API details.

## Project module imports

Source files inside a project's `source` directory (declared in `rank.toml`) are accessible under the `root::` prefix using their path relative to that directory:

```text
src/
  main.rank
  config/
    defaults.rank
    overrides.rank
```

```rank
// in src/main.rank
use root::config::defaults::{ base_port }
use root::config::overrides::{ production_host }

// in src/config/overrides.rank
use super::defaults::{ base_port }

// in src/config.rank
use self::defaults::{ base_port }
```

```mermaid
graph LR
  std["std::collections"]:::stdlib
  defaults["root::config::defaults"]:::module
  overrides["root::config::overrides"]:::module
  main["src/main.rank"]:::module

  std --> main
  defaults --> main
  overrides --> main

  classDef stdlib fill:#f0f4e8,stroke:#4caf50
  classDef module fill:#fdf3e8,stroke:#ff9800
```

The DAG applies across modules too — the compiler resolves the full cross-module dependency graph and rejects cycles.

Relative anchors are only for project-local modules. Package, provider, and stdlib imports continue to use their ordinary namespace prefixes.

## Exports and visibility

Declarations are private by default. Mark a declaration `pub` to export it:

```rank
// in src/config/defaults.rank
base_port = 3000        // private — not importable from other modules

pub api_port = 8080     // exported
pub db_port = 5432      // exported
```

Imported names are not automatically re-exported. Use top-level named `pub use` when you want a module to act as a facade:

```rank
// in src/billing.rank
pub use self::types::{ Quote }
pub use self::pricing::{ quote }

// in src/main.rank
use root::billing::{ Quote, quote }
```

Named `pub use` re-exports the matching public bindings from the target module. If the same spelling exists in both the value and type namespaces, the same `pub use` surface re-exports both. Wildcard re-exports such as `pub use self::types::*` are not supported.

## Provider imports

Provider namespaces are imported the same way as other modules. The provider must be registered in `rank.toml` first (see the [Provider guide](../faker-provider.mdx)):

```rank
use faker::{ Generate, UUID, Int }
use faker::types::{ Spec }
```

The provider namespace corresponds to the `namespace` field in the provider's `rank.toml`.

## Project manifest

Every project needs a `rank.toml` at its root. The `source` field declares the directory that becomes the `root::` module tree:

```toml
manifestVersion = 1

[package]
name = "my-project"
version = "0.1.0"
source = "src"
```

To register a provider:

```toml
[providers]
faker = { path = "./providers/faker" }
```

Dependency aliases in `[dependencies]` can point at local packages, npm-published packages, or git-backed packages. Provider aliases in `[providers]` can point at local providers or npm-published provider packages.

For packaging and publishing guidance, see [Dependencies](../dependencies.mdx) and [Provider authoring](/docs/provider-authoring). For the full `rank.toml` schema, including dependencies, registries, security defaults, and provider-package metadata, see the [Manifest Reference](../manifest-reference.mdx).

---

## Mutations


`std::Mutation` is the language-level boundary for provider-backed writes. The important rule is that Rank does not execute a provider mutation at the moment you call the effect binding. Instead, mutation work is split into fulfillment and commit so the program can stay deterministic during ordinary evaluation and only perform external I/O when a host explicitly realizes a top-level `Mutation::commit(...)` descriptor.

## Why plan and commit are separate

Rank keeps provider mutations explicit for three reasons:

- fulfilled mutation values can feed later mutation payloads before anything is committed
- hosts must admit provider capabilities and exact mutation export names before any external write runs
- commit results need one projection point so the final output can include success, rejection, unknown outcomes, and receipt metadata in an ordinary document shape

That is why `Mutation::Effect<T>`, `Mutation::plan(...)`, and `Mutation::commit(...)` are separate surfaces instead of one eager `mutate(...)` function.

## Lifecycle

### 1. Declare an effect binding

`Mutation::Effect<T>` marks a required external write whose fulfillment payload has type `T`. The annotated binding must be a direct call to a provider `mutation` export.

```rank
use std::Mutation

Entry = Object {
  id: string,
  label: string,
}

writeEntry: Mutation::Effect<Entry> = my_provider::actions::write<Entry> {
  table: `entries`,
}
```

Values like `table` above are declaration-time configuration. The actual payload for the write is provided later when the effect binding is called.

### 2. Fulfill effects during ordinary evaluation

Calling an effect binding fulfills one required write. That call still does not commit provider I/O. It produces a commit-local value that may feed later mutation inputs:

```rank
use std::Mutation

Entry = Object {
  id: string,
  label: string,
}

TaggedEntry = Object {
  id: string,
  tag: string,
  label: string,
}

writeEntry: Mutation::Effect<Entry> = my_provider::actions::write<Entry> {
  table: `entries`,
}

writeTaggedEntry: Mutation::Effect<TaggedEntry> = my_provider::actions::write<TaggedEntry> {
  table: `entry-tags`,
}

createdEntry = writeEntry({
  id: `1`,
  label: `alpha`,
})

taggedEntry = writeTaggedEntry({
  id: createdEntry.id,
  tag: `fresh`,
  label: `entry-${createdEntry.label}`,
})
```

The key distinction is:

- `createdEntry` is the fulfilled payload value, not provider receipt metadata
- that value is commit-local, so it can feed later mutation inputs
- it must not escape into ordinary public output or drive control flow such as the conditional `condition ? whenTrue : whenFalse` expression or `match`

### 3. Build a plan

`Mutation::plan(...)` collects required operations into one opaque plan descriptor:

```rank
use std::Mutation

Entry = Object {
  id: string,
  active: bool,
}

writeUser: Mutation::Effect<Entry> = my_provider::actions::write<Entry> {
  table: `users`,
}

writeAudit: Mutation::Effect<Entry> = my_provider::actions::write<Entry> {
  table: `audit`,
}

plan = Mutation::plan({
  createdUser: writeUser({ id: `1`, active: true }),
  auditUser: writeAudit({ id: `2`, active: false }),
})
```

Each field label becomes one typed `report.operations.<label>` entry inside the projector passed to `Mutation::commit(...)`.

If a plan is never consumed by `Mutation::commit(...)`, no side effect runs.

### 4. Commit the plan and project the outcomes

`Mutation::commit(...)` turns a plan into `std::Emit<T>`. Its projector receives a `Mutation::CommitReport<Ops>` with aggregate status plus one typed per-operation result:

```rank
use std::Mutation

Entry = Object {
  id: string,
  active: bool,
}

writeUser: Mutation::Effect<Entry> = my_provider::actions::write<Entry> {
  table: `users`,
}

plan = Mutation::plan({
  createdUser: writeUser({ id: `1`, active: true })
})

pub main = ||
  Mutation::commit(
    plan,
    |report| {
      status: report.status,
      createdUser: report.operations.createdUser,
    },
  )
```

`report.status` is the aggregate commit status for the whole plan. `report.operations.createdUser` is a `Mutation::Result<Value, Receipt>` for that specific operation label.

The projector must return one ordinary emit-compatible document value. Returning another `std::Emit<T>` from inside the projector is rejected for the same reason nested `Emit::manifest(...)` descriptors are rejected elsewhere.

## When does the side effect actually happen?

This is the practical rule to remember:

- declaring `Mutation::Effect<T>` is static
- calling an effect binding fulfills a required write, but still does not execute provider I/O
- `Mutation::plan(...)` is pure and opaque
- the actual external write happens only when a host realizes a top-level `Mutation::commit(...)` descriptor

In practice that means:

- `rank check` and editor diagnostics never commit provider mutations
- `rank src/main.rank` commits only when `pub main` returns top-level `Mutation::commit(...)`
- `rank serve` can commit when a handler returns `Mutation::commit(...)` as the top-level `HTTP::Response.body`

The explicit commit boundary exists so Rank can keep ordinary evaluation deterministic while still making side effects visible, typed, and host-admitted.

## Result shapes

`Mutation::Result<Value, Receipt>` is the per-operation discriminated union:

- `Mutation::Succeeded<Value, Receipt> = Object { status: `succeeded`, value: Value, receipt: Receipt }`
- `Mutation::Rejected = Object { status: `rejected`, error: Object { code: string, message: string }, notes?: [string] }`
- `Mutation::Unknown = Object { status: `unknown`, message: string, notes?: [string] }`
- `Mutation::NotStarted = Object { status: `not-started` }`

`Mutation::CommitReport<Ops>` is the aggregate object passed to the projector:

- `Mutation::CommitReport<Ops> = Object { status: `succeeded` | `rejected` | `unknown`, operations: Ops }`

`Mutation::Receipt<R>` names the provider receipt metadata type retained on successful outcomes. Effect calls do not return `Mutation::Receipt<R>` directly during ordinary compute.

`not-started` appears on individual operations when an earlier dependency prevented that write from running. The aggregate `report.status` collapses the overall commit to `succeeded`, `rejected`, or `unknown`.

## Rules and constraints

- effect bindings must be fulfilled exactly once on every reachable code path
- fulfilled values may be read, transformed, and assembled into later mutation payloads
- commit-local fulfilled values must not appear in ordinary `pub` outputs or in ordinary external-input reads such as `Env`, `File::Read`, or `HTTP::Fetch`
- commit-local fulfilled values must not drive conditional expressions, `match`, or any other construct that changes program topology
- fulfilling an effect is always scalar; automatic lifting does not fan one effect out across lists or objects

## Related pages

- See [Standard library](./stdlib.mdx) for the raw `std::Mutation` surface reference.
- See [Output and manifests](./output.mdx) for how `std::Emit<T>` descriptors behave at the top level.
- See [AWS provider](../aws-provider.mdx) for a provider-specific end-to-end example with host admission and `rank.toml` setup.

---

## Output and manifests


Rank programs usually return one of two result shapes from `pub main`:

- an ordinary emit-compatible document value
- an opaque `std::Emit<T>` descriptor such as `Emit::manifest(...)` or `Mutation::commit(...)`

The distinction matters because the CLI treats them differently.

## Single-document output

The simplest program returns one structured value:

```rank
config = {
  host: `api.example.com`,
  port: 8080,
}

pub main = || config
```

Running the program prints YAML to stdout by default:

```sh
rank src/main.rank
```

```yaml
host: api.example.com
port: 8080
```

Pass `--format json` to emit the same value as JSON instead:

```sh
rank src/main.rank --format json
```

```json
{
  "host": "api.example.com",
  "port": 8080
}
```

Field order is preserved exactly as the program evaluates it.

## Multi-file output with `Emit::manifest`

Use `std::Emit` when one evaluation should describe multiple artifacts.

```rank
use std::Emit
use std::Path

manifest = Emit::manifest({
  entries: [
    {
      path: Path::from(`README.md`),
      format: `text`,
      value: `# api\n`,
    },
    {
      path: Path::join([`k8s`, `deployment.yaml`]),
      format: `yaml`,
      value: {
        service: {
          name: `api`,
          port: 8080,
        },
      },
    },
  ]
})

pub main = || manifest
```

Each entry has three parts:

- `path` — a `Path::RelativePath`, not a raw string path
- `format` — one of ``json``, ``yaml``, or ``text``
- `value` — the payload to emit for that file

`std::Emit<T>` is a pure descriptor. Constructing it does not write anything to disk or perform commit execution during ordinary evaluation.

## What the CLI does

When `pub main` returns an ordinary document, `rank <entry>` prints YAML by default and accepts `--format json` for JSON output.

When `pub main` returns `Emit::manifest(...)`, `rank <entry>` prints a descriptor envelope to stdout instead. YAML remains the default, and `--format json` switches the descriptor envelope to JSON:

```yaml
kind: rank/output-manifest
version: 1
entries:
  - path: README.md
    format: text
    value: |
      # api
  - path: k8s/deployment.yaml
    format: yaml
    value:
      service:
        name: api
        port: 8080
```

To materialize those files on disk, pass an explicit output root:

```sh
rank src/main.rank --file-root ./out
```

The CLI still prints the descriptor to stdout, then applies the entries under `./out` as a second stage.

## Common mistakes

- Duplicate destination paths are errors, including duplicates that appear only after path normalization.
- `format: \`text\`` requires `value` to be a string.
- `--file-root` is valid only when `pub main` returns `Emit::manifest(...)`.
- Nested `std::Emit<T>` values are not allowed inside ordinary objects or lists; the descriptor must be the top-level `pub main` result.
- Paths are relative by design. Absolute paths and upward escapes are rejected by `std::Path`.

## Related pages

- See [Standard library](./stdlib.mdx) for the `std::Emit` and `std::Path` signatures.
- See [Mutations](./mutations.mdx) for the `Mutation::plan(...)` / `Mutation::commit(...)` lifecycle.
- See [CLI reference](../cli.mdx) for `--file-root` and command behavior.
- See [Examples](../examples/index.mdx) for complete manifest-producing programs.

---

## Standard library


The standard library is organized into pure modules under the `std::` prefix. All functions are standalone — there are no methods on values.

Signatures use generic type parameters (`A`, `B`, `T`, `R`) to indicate where types are determined by the call site. The iteration context type is abbreviated as:

```rank
IterCtx = Object {
  index: number,
  size: number,
  isFirst: bool,
  isLast: bool,
}
```

---

## `std::collections`

Generic collection operations. Most work on both lists and objects via automatic lifting.

### `map`

```rank
map(collection: [A], callback: |A| -> B) -> [B]
map(collection: [A], callback: |A, IterCtx| -> B) -> [B]
```

Apply a function to every element:

```rank
use std::collections::{ map }

doubled = map([1, 2, 3], |x| x * 2)        // [2, 4, 6]
```

The callback may accept an iteration context as a second argument:

```rank
indexed = map([`a`, `b`, `c`], |item, ctx| {
  return { value: item, index: ctx.index }
})
```

### `filter`

```rank
filter(collection: [A], predicate: |A| -> bool) -> [A]
filter(collection: [A], predicate: |A, IterCtx| -> bool) -> [A]
```

Keep only elements for which the predicate returns `true`:

```rank
use std::collections::{ filter }

evens = filter([1, 2, 3, 4], |x| x % 2 == 0)    // [2, 4]
```

### `flatMap`

```rank
flatMap(collection: [A], callback: |A| -> [B]) -> [B]
flatMap(collection: [A], callback: |A, IterCtx| -> [B]) -> [B]
```

Map then flatten one level:

```rank
use std::collections::{ flatMap }

expanded = flatMap([1, 2, 3], |x| [x, x * 10])   // [1, 10, 2, 20, 3, 30]
```

### `find`

```rank
find(collection: [A], predicate: |A| -> bool) -> A | null
find(collection: [A], predicate: |A, IterCtx| -> bool) -> A | null
```

Return the first matching element, or `null` if none matches:

```rank
use std::collections::{ find }

first_even = find([1, 3, 4, 5], |x| x % 2 == 0)   // 4
missing    = find([1, 3, 5], |x| x % 2 == 0)       // null
```

### `any`

```rank
any(collection: [A], predicate: |A| -> bool) -> bool
any(collection: [A], predicate: |A, IterCtx| -> bool) -> bool
```

Return `true` if at least one element satisfies the predicate:

```rank
use std::collections::{ any }

has_large = any([1, 2, 100], |x| x > 50)   // true
```

### `all`

```rank
all(collection: [A], predicate: |A| -> bool) -> bool
all(collection: [A], predicate: |A, IterCtx| -> bool) -> bool
```

Return `true` if every element satisfies the predicate:

```rank
use std::collections::{ all }

all_pos = all([1, 2, 3], |x| x > 0)   // true
```

### `count`

```rank
count(collection: [A], predicate: |A| -> bool) -> number
count(collection: [A], predicate: |A, IterCtx| -> bool) -> number
```

Count elements satisfying a predicate:

```rank
use std::collections::{ count }

n = count([1, 2, 3, 4], |x| x % 2 == 0)   // 2
```

### `length`

```rank
length(value: string) -> number
length(value: [A]) -> number
length(value: Object { ...: A }) -> number
```

Return the size of a string, list, or object:

```rank
use std::collections::{ length }

string_len = length(`rank`)                // 4
list_len   = length([1, 2, 3])             // 3
object_len = length({ http: 80, https: 443 }) // 2
```

### `reduce`

```rank
reduce(collection: [A], initial: R, step: |R, A| -> R) -> R
reduce(collection: [A], initial: R, step: |R, A, IterCtx| -> R) -> R
```

Left fold with an explicit initial accumulator. Returns `initial` unchanged when the list is empty:

```rank
use std::collections::{ reduce }

sum = reduce([1, 2, 3, 4], 0, |acc, x| acc + x)   // 10
```

### `reverse`

```rank
reverse(collection: [A]) -> [A]
```

Return a reversed copy of a list:

```rank
use std::collections::{ reverse }

reversed = reverse([1, 2, 3])   // [3, 2, 1]
```

### `zip`

```rank
zip(left: [A], right: [B]) -> [Object { left: A, right: B }]
```

Pair elements from two equal-length lists by index. Lists must have the same length:

```rank
use std::collections::{ zip }

pairs = zip([1, 2, 3], [`a`, `b`, `c`])
// [{ left: 1, right: `a` }, { left: 2, right: `b` }, { left: 3, right: `c` }]
```

### `groupBy`

```rank
groupBy(collection: [A], keyFn: |A| -> string) -> Object { ...: [A] }
groupBy(collection: [A], keyFn: |A, IterCtx| -> string) -> Object { ...: [A] }
```

Group elements by a string key. Groups appear in first-encounter order; elements within each group preserve input order:

```rank
use std::collections::{ groupBy }

grouped = groupBy([1, 2, 3, 4], |x| x % 2 == 0 ? `even` : `odd`)
// { odd: [1, 3], even: [2, 4] }
```

### `keyBy`

```rank
keyBy(collection: [A], keyFn: |A| -> string) -> Object { ...: A }
keyBy(collection: [A], keyFn: |A, IterCtx| -> string) -> Object { ...: A }
```

Index a list into an object by a key function. Duplicate keys are errors:

```rank
use std::collections::{ keyBy }

indexed = keyBy([{ id: `a`, v: 1 }, { id: `b`, v: 2 }], |item| item.id)
// { a: { id: `a`, v: 1 }, b: { id: `b`, v: 2 } }
```

### `sort`

```rank
sort(list: [number]) -> [number]
sort(list: [string]) -> [string]
sort(obj: Object { ...: T }) -> Object { ...: T }
```

Sort a list of numbers or strings in ascending order. Sort an object's fields lexicographically by key. Stable:

```rank
use std::collections::{ sort }

sorted_list = sort([3, 1, 2])               // [1, 2, 3]
sorted_obj  = sort({ zebra: 1, alpha: 2 }) // { alpha: 2, zebra: 1 }
```

### `sortBy`

```rank
sortBy(collection: [A], keyFn: |A| -> number | string) -> [A]
sortBy(collection: [A], keyFn: |A, IterCtx| -> number | string) -> [A]
```

Sort a list by a projected numeric or string key. Stable ascending order:

```rank
use std::collections::{ sortBy }

people = [{ name: `carol`, age: 30 }, { name: `alice`, age: 25 }]
by_name = sortBy(people, |p| p.name)   // alice first
```

---

## `std::list`

List-specific operations.

### `range`

```rank
range(end: number) -> [number]
range(start: number, end: number) -> [number]
range(start: number, end: number, step: number) -> [number]
```

Produce a list of consecutive integers over the half-open interval `[start, end)`. Single-argument form treats `start` as `0`:

```rank
use std::list::{ range }

r = range(5)       // [0, 1, 2, 3, 4]
s = range(2, 5)    // [2, 3, 4]
t = range(0, 10, 2) // [0, 2, 4, 6, 8]
```

### `flatten`

```rank
flatten(list: [[A]]) -> [A]
```

Flatten one level of nesting:

```rank
use std::list::{ flatten }

flat = flatten([[1, 2], [3, 4]])   // [1, 2, 3, 4]
```

### `slice`

```rank
slice(list: [A], start: number) -> [A]
slice(list: [A], start: number, end: number) -> [A]
```

Extract a sub-list over `[start, end)`. Negative indices count from the end. Out-of-range indices are clipped:

```rank
use std::list::{ slice }

s = slice([10, 20, 30, 40, 50], 1, 3)   // [20, 30]
t = slice([10, 20, 30, 40, 50], -2)     // [40, 50]
```

### `transpose`

```rank
transpose(list: [[A]]) -> [[A]]
```

Transpose a list of equal-length lists (swap rows and columns):

```rank
use std::list::{ transpose }

t = transpose([[1, 2], [3, 4], [5, 6]])   // [[1, 3, 5], [2, 4, 6]]
```

---

## `std::object`

Object-specific operations.

### `mapValues`

```rank
mapValues(obj: Object { ...: A }, callback: |A, string| -> B) -> Object { ...: B }
```

Transform each value. The callback receives `(value, key)`. Preserves field order:

```rank
use std::object::{ mapValues }

doubled = mapValues({ a: 1, b: 2 }, |value, key| value * 2)   // { a: 2, b: 4 }
```

### `keys`

```rank
keys(obj: Object { ...: T }) -> [string]
```

```rank
use std::object::{ keys }

ks = keys({ a: 1, b: 2 })   // [`a`, `b`]
```

### `values`

```rank
values(obj: Object { ...: T }) -> [T]
```

```rank
use std::object::{ values }

vs = values({ a: 1, b: 2 })   // [1, 2]
```

### `entries`

```rank
entries(obj: Object { ...: T }) -> [Object { key: string, value: T }]
```

```rank
use std::object::{ entries }

es = entries({ a: 1, b: 2 })
// [{ key: `a`, value: 1 }, { key: `b`, value: 2 }]
```

### `fromEntries`

```rank
fromEntries(entries: [Object { key: string, value: T }]) -> Object { ...: T }
```

Build an object from a list of `{ key, value }` pairs. Duplicate keys are errors:

```rank
use std::object::{ fromEntries }

obj = fromEntries([{ key: `host`, value: `localhost` }, { key: `port`, value: 8080 }])
// { host: `localhost`, port: 8080 }
```

---

## `std::string`

String-specific normalization and search helpers.

### `trim`

```rank
trim(text: string) -> string
```

Remove leading and trailing Unicode whitespace:

```rank
use std::string::{ trim }

trimmed = trim(`  rank  `)   // `rank`
```

### `split`

```rank
split(text: string, delimiter: string) -> [string]
```

Split a string on a literal non-empty delimiter. Empty segments are preserved:

```rank
use std::string::{ split }

parts = split(`api,worker`, `,`)   // [`api`, `worker`]
```

### `contains`

```rank
contains(text: string, needle: string) -> bool
```

```rank
use std::string::{ contains }

has_inner = contains(`rank`, `an`)   // true
```

### `startsWith`

```rank
startsWith(text: string, prefix: string) -> bool
```

```rank
use std::string::{ startsWith }

has_prefix = startsWith(`rank`, `ra`)   // true
```

### `endsWith`

```rank
endsWith(text: string, suffix: string) -> bool
```

```rank
use std::string::{ endsWith }

has_suffix = endsWith(`rank`, `nk`)   // true
```

### `isBlank`

```rank
isBlank(text: string) -> bool
```

Return `true` when the string is empty after trimming whitespace:

```rank
use std::string::{ isBlank }

blank = isBlank(`   `)   // true
```

This is a convenient validation helper for field constraints and declaration constraints:

```rank
use std::string::{ isBlank }

@constraint(cond: |self| !isBlank(self))
service_name = `api`
```

---

## `std::Regex`

Regular expression operations. Regex literals use the `re` prefix: `re`foo-[0-9]+``.

### `matches`

```rank
matches(text: string, pattern: Regex) -> bool
matches(text: string, pattern: Regex, options: Object { caseInsensitive?: bool, multiline?: bool, dotAll?: bool }) -> bool
```

Return `true` when the pattern matches the **entire** string:

```rank
use std::Regex::{ matches }

valid = matches(`v1.2.3`, re`v[0-9]+\.[0-9]+\.[0-9]+`)   // true
```

### `search`

```rank
search(text: string, pattern: Regex) -> bool
search(text: string, pattern: Regex, options: Object { caseInsensitive?: bool, multiline?: bool, dotAll?: bool }) -> bool
```

Return `true` when the pattern matches **anywhere** in the string:

```rank
use std::Regex::{ search }

found = search(`deploy ABC-123 today`, re`[A-Z]+-[0-9]+`)   // true
```

### `replace`

```rank
replace(text: string, pattern: Regex, replacement: string) -> string
replace(text: string, pattern: Regex, replacement: string, options: Object { caseInsensitive?: bool, multiline?: bool, dotAll?: bool }) -> string
```

Replace all non-overlapping matches. Replacement strings are literal — no `$1`-style back-references:

```rank
use std::Regex::{ replace }

normalized = replace(`ticket ABC-123`, re`[A-Z]+-[0-9]+`, `TICKET`)
// `ticket TICKET`
```

### `captures`

```rank
captures(text: string, pattern: Regex) -> Object { full: string, groups: [string | null] } | null
captures(text: string, pattern: Regex, options: Object { caseInsensitive?: bool, multiline?: bool, dotAll?: bool }) -> Object { full: string, groups: [string | null] } | null
```

Return the first match with its capture groups, or `null` if no match:

```rank
use std::Regex::{ captures }

result = captures(`ticket ABC-123`, re`([A-Z]+)-([0-9]+)`)
// { full: `ABC-123`, groups: [`ABC`, `123`] }
```

---

## `std::Time`

Pure time operations over structural `Time::Instant` and `Time::Duration` values. No implicit access to the host clock.

```rank
Time::Instant  = Object { epochMillis: number, offsetMinutes: number }
Time::Duration = Object { millis: number }
Time::TimeZone = `UTC` | `preserveOffset`
```

### `Time::parse`

```rank
Time::parse(text: string, options: Object { format: `RFC3339` }) -> Time::Instant
```

```rank
use std::Time

instant = Time::parse(`2024-01-15T12:00:00Z`, { format: `RFC3339` })
```

### `Time::format`

```rank
Time::format(instant: Time::Instant, options: Object { format: `RFC3339`, timezone: Time::TimeZone }) -> string
```

```rank
rendered = Time::format(instant, { format: `RFC3339`, timezone: `UTC` })
```

### `Time::add`

```rank
Time::add(instant: Time::Instant, duration: Time::Duration) -> Time::Instant
```

```rank
later = Time::add(instant, Time::minutes(15))
```

### `Time::diff`

```rank
Time::diff(left: Time::Instant, right: Time::Instant) -> Time::Duration
```

Returns the duration `left - right`.

### Duration constructors

```rank
Time::seconds(n: number) -> Time::Duration
Time::minutes(n: number) -> Time::Duration
Time::hours(n: number)   -> Time::Duration
```

---

## `std::Path`

Pure relative filesystem-style path operations.

```rank
Path::RelativePath   // opaque path value
```

### `Path::from`

```rank
Path::from(text: string) -> Path::RelativePath
```

Parse a forward-slash-separated relative path string. Rejects absolute paths and upward escapes:

```rank
use std::Path

p = Path::from(`configs/production.yaml`)
```

### `Path::join`

```rank
Path::join(segments: [string]) -> Path::RelativePath
```

Construct a path from a list of single segments (no `/` allowed within a segment):

```rank
deployment = Path::join([`k8s`, `deployment.yaml`])
```

### `Path::toString`

```rank
Path::toString(path: Path::RelativePath) -> string
```

Return the canonical forward-slash rendering:

```rank
label = Path::toString(Path::join([`k8s`, `service.yaml`]))
// `k8s/service.yaml`
```

---

## `std::Emit`

Entrypoint-only emit descriptor constructors. `std::Emit<T>` is not directly emit-compatible inside ordinary objects or lists; the host realizes it when it is returned from ordinary `pub main`, and serve-time JSON/YAML responses may also realize a top-level `std::Emit<T>` body before serialization.

### `Emit::Format`

```rank
Emit::Format = `json` | `yaml` | `text`
```

### `Emit::manifest`

```rank
Emit::manifest<T>: (Object {
  entries: [Object {
    path: Path::RelativePath,
    format: Emit::Format,
    value: unknown,
  }]
}) -> std::Emit<T>
```

```rank
use std::Emit
use std::Path

manifest = Emit::manifest({
  entries: [
    { path: Path::join([`k8s`, `deploy.yaml`]), format: `yaml`, value: { name: `api` } },
    { path: Path::from(`README.md`),            format: `text`, value: `# api\n` },
  ]
})

pub main = || manifest
```

Duplicate destination paths are errors. `text` entries require a `string` value; `json` and `yaml` entries accept any ordinary emit-compatible Rank value. `Emit::manifest(...)` is pure: it does not write to disk until a host command such as `rank <entry> --file-root <dir>` chooses to materialize it.

---

## `std::Rand`

Seeded deterministic randomness. No ambient entropy — all randomness is derived from an explicit seed value.

```rank
Rand::Rng     = Object { algorithm: string, state: string }
Rand::Draw<T> = Object { value: T, rng: Rand::Rng }
```

Every draw function returns both the sampled value and the successor RNG, so sequencing is explicit.

### `Rand::seed`

```rank
Rand::seed(seed: number) -> Rand::Rng
```

```rank
use std::Rand

rng = Rand::seed(42)
```

### `Rand::derive`

```rank
Rand::derive(rng: Rand::Rng, label: string) -> Rand::Rng
```

Derive a stable labeled sub-stream. Use this to create independent sequences that do not interfere with each other:

```rank
color_rng = Rand::derive(rng, `color`)
size_rng  = Rand::derive(rng, `size`)
```

### `Rand::int`

```rank
Rand::int(rng: Rand::Rng, range: Object { min: number, max: number }) -> Rand::Draw<number>
```

Draw an integer in the inclusive range `[min, max]`:

```rank
{ value: roll, rng: rng2 } = Rand::int(rng, { min: 1, max: 6 })
```

### `Rand::float`

```rank
Rand::float(rng: Rand::Rng) -> Rand::Draw<number>
Rand::float(rng: Rand::Rng, range: Object { min: number, max: number }) -> Rand::Draw<number>
```

Draw a float in `[0, 1)`, or in `[min, max)` with explicit bounds.

### `Rand::bool`

```rank
Rand::bool(rng: Rand::Rng, options?: Object { probability?: number }) -> Rand::Draw<bool>
```

Draw a boolean. `probability` defaults to `0.5`.

### `Rand::choose`

```rank
Rand::choose(rng: Rand::Rng, list: [A]) -> Rand::Draw
```

Pick one element uniformly at random. Error if `list` is empty.

### `Rand::shuffle`

```rank
Rand::shuffle(rng: Rand::Rng, list: [A]) -> Rand::Draw<[A]>
```

Return a randomly permuted copy of the list.

---

## `std::types`

Compile-time utility types for deriving new types from existing ones. Import them from `std::types` and use them only in type positions.

```rank
use std::types::{ Pick, Omit, Partial, Required, Record, Exclude, Extract, NonNullable, DeepPartial }

User = Object {
  id: string,
  name: string,
  email?: string,
  passwordHash: string,
}

Summary = Pick<User, `id` | `name`>
PublicUser = Omit<User, `passwordHash`>
Draft = Partial<User>
CompleteDraft = Required<Partial<User>>
Flags = Record<`featureA` | `featureB`, bool>
TextOnly = Extract<string | number, string>
NumberOnly = Exclude<string | number, string>
Email = NonNullable<User[`email`]>
```

| Utility | Effect |
|---|---|
| `Pick<T, K extends keyof T>` | Keep only fields `K` from object `T` |
| `Omit<T, K extends keyof T>` | Remove fields `K` from object `T` |
| `Partial<T>` | Make object fields optional |
| `Required<T>` | Make object fields required |
| `Record<K, V>` | Construct an object type with keys `K` and value type `V` |
| `Exclude` | Remove union members assignable to `B` from `A` |
| `Extract` | Keep union members assignable to `B` |
| `NonNullable<T>` | Remove `null` from `T` |
| `DeepPartial<T>` | Recursively make nested object fields optional |

`Pick` and `Omit` reject keys outside `keyof T` at the alias boundary.

`keyof` and indexed access types such as `User[`profile`]` are language operators rather than `std::types` imports; see [Values and types](./values-and-types#type-queries-and-utility-types).

---

## `std::Decode`

`Decode<T>(text)` converts boundary text into a typed value of `T`. The result is `T | null`: `null` means the text did not match `T`.

```rank
use std::Decode

Port = 8080 | 8443 | 9000

decoded_port = Decode<Port>(`8443`) ?? 8080

SysEnv = Object {
  PORT?: Decode<Port>,
  DEBUG?: Decode<bool>,
  ...: string,
}

env = Env<SysEnv> {}
```

Use `Decode<T>` when external systems supply strings but the rest of the program wants numbers, booleans, or literal unions. It keeps parsing at the boundary instead of normalizing raw strings later in the program.

---

## `std::Mutation`

`std::Mutation` is the standard-library surface for provider-backed writes and commit-aware output projection.

### Surface

```rank
use std::Mutation

Mutation::Effect<T>
Mutation::Receipt<R>
Mutation::Succeeded<Value, Receipt>
Mutation::Rejected
Mutation::Unknown
Mutation::NotStarted
Mutation::Result<Value, Receipt>
Mutation::CommitReport<Ops>

Mutation::plan(...)
Mutation::commit(...)
```

There is no separate `std::Mutate` module or function. The surface name is `std::Mutation`.

At a high level:

- `Mutation::Effect<T>` declares a provider-backed write whose fulfilled payload has type `T`
- `Mutation::plan(...)` collects labeled operations into one opaque plan value
- `Mutation::commit(...)` turns that plan into a top-level `std::Emit<T>` descriptor
- `Mutation::Result<Value, Receipt>` and `Mutation::CommitReport<Ops>` describe per-operation and aggregate commit outcomes

Use the `std::Mutation` names here as the raw surface reference. For the full lifecycle, examples, commit timing, result shapes, and constraints, see [Mutations](./mutations.mdx).

---

## External input built-ins

These are part of the language, not importable modules.

### `Env<T> {}`

Read environment variables from the host. The type parameter declares the expected schema. Only declared fields are materialized:

```rank
SysEnv = Object {
  DATABASE_URL: string,
  PORT?: string,
  ...: string,
}

env = Env<SysEnv> {}
port = env.PORT ?? `5432`
```

The environment is snapshotted exactly once per compilation.

### `File::Read<T> { path, format }`

Read a structured file at a statically-known relative path:

```rank
Items = [Object { name: string, value: number }]

response = File::Read<Items> {
  path: Path::from(`./data/items.json`),
  format: `json`,
}

data = response.body
```

The result shape:

| Field | Type | Description |
|---|---|---|
| `body` | `T` | Parsed, type-checked file contents |
| `ctx` | `Object { path: string, format: string }` | Metadata about the read |

`dotenv` is also supported for `.env`-style flat text files:

- the decoded shape is a flat string-keyed object
- field-local `Decode` and schema-wide `File::Read<Decode<T>>` use the same scalar-only decoding rules as `Env<T> {}`
- interpolation and shell evaluation are intentionally not supported

```rank
use std::Decode

Config = Object {
  PORT?: Decode<8080 | 9000>,
  DEBUG?: Decode<bool>,
  ...: string,
}

response = File::Read<Config> {
  path: Path::from(`./.env`),
  format: `dotenv`,
}

port = response.body.PORT ?? 8080
```

Supported formats: `json`, `yaml`, `csv`, `dotenv`. CSV rows decode to header-keyed objects with string values. Dotenv rows decode to flat text fields with optional `Decode<...>` at the same boundary. `path` must be statically evaluable before any external input execution.

### `HTTP::Fetch<T> { url, method, headers?, cacheKey }`

Make a network request and decode the response body against `T`:

```rank
use std::HTTP

Body = Object {
  users: [Object { id: number, name: string }],
}

response = HTTP::Fetch<Body> {
  url: `https://api.example.com/users`,
  method: `GET`,
  headers: {
    Accept: `application/json`,
  },
  cacheKey: `users-v1`,
}

users = response.body.users
status = response.ctx.status
```

Request fields:

| Field | Required | Description |
|---|---|---|
| `url` | yes | Request URL |
| `method` | yes | HTTP method (`GET`, `POST`, etc.) |
| `headers` | no | Object of header name → value strings |
| `cacheKey` | yes | Stable key for deterministic replay |

The result shape:

| Field | Type | Description |
|---|---|---|
| `body` | `T` | Parsed, type-checked response body |
| `ctx` | see below | Request metadata |

`ctx` fields:

| Field | Type | Description |
|---|---|---|
| `status` | `number` | HTTP status code |
| `cacheKey` | `string` | The `cacheKey` from the request |
| `headers` | `Object { ...: string }` | Response headers |

`cacheKey` is required for determinism — see [HTTP snapshot caching](./external-inputs#http-snapshot-caching) for how to capture and replay responses offline.

---

## Values and types


Rank values are immutable. Once a value is produced it cannot be changed. There is no mutation, no variable reassignment, and no mutable state anywhere in the language.

## Primitive values

| Kind | Examples |
|---|---|
| `string` | `` `hello` ``, `` `port: 8080` `` |
| `number` | `42`, `3.14`, `-1` |
| `bool` | `true`, `false` |
| `null` | `null` |

String literals use **backticks** as their only delimiter. They may span multiple lines and support `${...}` interpolation when each interpolated expression has type `string`:

```rank
name = `world`
greeting = `Hello, ${name}!`
```

Regular expression literals use the `re` prefix:

```rank
pattern = re`foo-[0-9]+`
```

## Structured values

**Lists** are ordered sequences:

```rank
ports = [80, 443, 8080]
names = [`alice`, `bob`, `carol`]
```

**Objects** are ordered maps of named fields:

```rank
config = {
  host: `localhost`,
  port: 5432,
}
```

Field order is preserved in emitted output. There is no implicit reordering.

## Type aliases

Types are declared with leading-uppercase names. The bare `Name = Type` form creates a type alias:

```rank
Config = Object {
  host: string,
  port: number,
}

StringList = [string]
```

Generic type aliases use angle brackets. Parameters may be plain names, bounded with `extends`, or trailing-defaulted with `=`:

```rank
Box<T = string> = Object {
  value: T,
}

Pair = Object {
  left: A,
  right: B,
}

Field<T, K extends keyof T = `name`> = T[K]
```

Bounds and defaults are resolved left to right, so later parameters may reference earlier ones, but not the other way around. Omitted type arguments are only allowed for the trailing defaulted suffix, so a bare `Box` reference is valid while `Pair<string>` is not.

Recursive generic aliases are supported when recursion comes back to the same alias with the same type arguments:

```rank
Tree<T> = Object {
  value: T,
  left: [Tree<T>],
  right: [Tree<T>],
}

LinkedList<T> = null | Object {
  head: T,
  tail: LinkedList<T>,
}
```

Changing-argument recursion is not supported:

```rank
Grow<T> = Object {
  next: Grow<[T]>,
}
```

Type aliases live in the type namespace. They cannot be used as value bindings.

## Parse template string types

Structured string formats can be captured as types with `parse` templates:

```rank
Version = parse`{major:number}-{minor:number}-{patch:number}`

version: Version = `1-2-3`
```

A `parse` template type matches only strings whose full text matches the template and whose named segments decode to the requested types.

This is a core language feature, not a server-only trick or a standard-library parser helper. Rank uses the same structured-text idea in three places:

- `parse` template types such as a `Version = parse ...` alias
- `parse` patterns inside `match` expressions
- route matching forms such as `HTTP::Route` path patterns with the `match` prefix

Use a `parse` template type when you want to say “only strings of this shape are valid here.” A value of type `Version` is still just a string at runtime; the type constrains which strings are allowed.

When you want to bind the decoded pieces, use the same `parse` syntax as a pattern:

```rank
majorOf = |text: string| -> number | null {
  return match text {
    parse`{major:number}-{minor:number}-{patch:number}` => major,
    _ => null,
  }
}
```

These types are useful for validated version strings, route fragments, tagged identifiers, and other structured text values. For the pattern-matching side of the language, see [Bindings and functions](./bindings.mdx#pattern-matching).

## Object types

Object types are **closed by default** — an object with extra fields does not match a closed type:

```rank
Config = Object {
  host: string,
  port: number,
}
```

Open object types accept additional fields beyond the declared ones:

```rank
// accepts any object with at least a `host` string field
HostConfig = Object {
  host: string,
  ...: string,    // additional fields may be any string-valued key
}
```

Optional fields use `?`:

```rank
ServerConfig = Object {
  host: string,
  port: number,
  tls?: bool,     // may be absent
}
```

Reading an absent optional field yields `null`. Use `??` for an explicit default:

```rank
cfg: ServerConfig = { host: `localhost`, port: 443 }
use_tls = cfg.tls ?? false
```

## Field annotations on object types

Ordinary object-type fields and refinement fields can carry `@constraint`, `@unique`, and `@sensitive` directly on the field definition:

```rank
use std::string::{ isBlank }

ServiceConfig = Object {
  @unique(group: service_ids)
  id: string,
  @constraint(cond: |self| !isBlank(self))
  name: string,
  @constraint(cond: |self| self >= 1)
  replicas: number,
  @sensitive
  apiToken?: string,
}
```

These annotations travel with the type:

- `self` inside a field constraint is the field value.
- Absent optional fields skip field validation and unique registration.
- Refinements inherit field annotations by default.
- `Pick<T, K>`, `Partial<T>`, and `Required<T>` preserve field annotations when the field survives.
- `Omit<T, K>` removes them with the field, and `Record<K, V>` creates fresh fields with no inherited annotations.
- Mapped bodies and rest fields do not accept field annotations in the current language surface.

## Type unions and intersections

Union types accept either shape:

```rank
StringOrNumber = string | number
Mode = `dev` | `prod` | `staging`
```

Intersection types require both shapes:

```rank
Named = Object { name: string }
Versioned = Object { version: number }
NamedAndVersioned = Named & Versioned
```

## Type queries and utility types

`keyof` produces the field-name union for an object type, and indexed access reads a field type from another type:

```rank
User = Object {
  profile: Object {
    displayName: string,
  },
}

UserKeys = keyof User
DisplayName = User[`profile`][`displayName`]
```

These operators are the building blocks for reusable type helpers. You can write constrained aliases that only accept valid object keys:

```rank
FieldOf<T, K extends keyof T> = T[K]

Profile = FieldOf<User, `profile`>
DisplayName = Profile[`displayName`]
```

The `extends` clause is a declaration-site constraint on the type parameter. Here it means `K` must be assignable to `keyof T`. If a call site instantiates `FieldOf<User, `missing`>`, the compiler reports a type-argument constraint error at the alias boundary.

Common reusable type transforms live under `std::types`:

```rank
use std::types::{ Pick, Omit, Partial, Required, Record, Exclude, Extract, NonNullable }

User = Object {
  id: string,
  name: string,
  email?: string,
  passwordHash: string,
}

Summary = Pick<User, `id` | `name`>
PublicUser = Omit<User, `passwordHash`>
Draft = Partial<User>
CompleteDraft = Required<Partial<User>>
Flags = Record<`featureA` | `featureB`, bool>
TextOnly = Extract<string | number, string>
NumberOnly = Exclude<string | number, string>
Email = NonNullable<User[`email`]>
```

`Pick` and `Omit` constrain their key parameters to `keyof T`, so invalid keys fail at alias instantiation rather than later in mapped-type evaluation.

The utility types fall into a few common groups:

| Utility family | Types | What they do |
|---|---|---|
| Object field selection | `Pick`, `Omit` | Keep or remove named fields from an object type. The key parameter is constrained to `keyof T`. |
| Object optionality | `Partial`, `Required`, `DeepPartial` | Make fields optional, required, or recursively optional. |
| Object construction | `Record` | Build an object type from a key union and a value type. |
| Union filtering | `Exclude`, `Extract`, `NonNullable` | Remove or keep union members based on assignability. |

These are ordinary compile-time aliases, not runtime functions. They can be composed with `keyof`, indexed access, conditional types, and your own constrained aliases.

`DeepPartial<T>` recursively makes nested object fields optional, including nested object values inside lists:

```rank
use std::types::{ DeepPartial }

Config = Object {
  nested: Object {
    count: number,
  },
  items: [Object {
    label: string,
  }],
}

draft: DeepPartial<Config> = {
  nested: {},
  items: [{}],
}
```

These utilities operate entirely at compile time. They refine how the compiler checks values; they do not add runtime fields or emitted output.

When a utility type preserves a field, it also preserves that field's annotations. This is what lets reusable constraints, uniqueness groups, and sensitive redaction survive through views such as `Pick<T, K>` and `Partial<T>`.

## Type annotations on bindings

Annotate a binding with `: Type` to ask the compiler to verify the type:

```rank
port: number = 8080
config: Config = { host: `localhost`, port: 5432 }
```

If the value does not match the declared type, the compiler reports an error before evaluation.

## Function types

Function types are written with `||` for the parameter list and `->` for the return type. They describe the shape of a function value:

```rank
Transform = |number| -> number
Predicate = |string| -> bool
BinaryOp  = |number, number| -> number
```

Zero-argument functions:

```rank
Thunk = || -> string
```

A function that matches a type alias must have compatible parameter types and return type:

```rank
Transform = |number| -> number

double: Transform = |x| -> number {
  return x * 2
}
```

## `null` semantics

`null` is an explicit value for interop and absence. It is distinct from a missing optional field:

```rank
value: string | null = null
```

`??` is the null-defaulting operator. It evaluates the right side only when the left is `null`:

```rank
result = potentially_null_value ?? `default`
```

Functions must explicitly handle `null`. Automatic lifting does not skip `null` inputs.

---

## Docker Compose


Generate a `docker-compose.yml` from typed service definitions, reading environment variables for deployment-specific overrides.

## Source

```rank title="examples/docker-compose/types.rank"
pub ServiceDef = Object {
  image: string,
  ports?: [string],
  environment: Object { ...: string },
  depends_on?: [string],
  restart: string,
}

pub NetworkDef = Object {
  driver: string,
}

pub VolumeDef = Object {
  driver: string,
}

pub Compose = Object {
  version: string,
  services: Object { ...: ServiceDef },
  networks?: Object { ...: NetworkDef },
  volumes?: Object { ...: VolumeDef },
}
```

```rank title="examples/docker-compose/main.rank"
/// Generates a Docker Compose file from typed service definitions.
/// Shows Env inputs for environment-specific overrides, the `with` patch
/// pattern for dev vs prod, and Emit::manifest to emit a YAML artifact.

use std::Env
use std::Emit
use std::Path
use root::types::{ Compose, ServiceDef }

SysEnv = Object {
  COMPOSE_ENV?: string,
  DB_PASSWORD?: string,
  ...: string,
}

env = Env<SysEnv> {}

compose_env = env.COMPOSE_ENV ?? `dev`
db_password = env.DB_PASSWORD ?? `changeme`

is_prod = compose_env == `prod`

base_api: ServiceDef = {
  image: `my-org/api:latest`,
  ports: [`8080:8080`],
  environment: {
    NODE_ENV: compose_env,
    DB_HOST: `db`,
    DB_PASSWORD: db_password,
  },
  depends_on: [`db`],
  restart: `on-failure`,
}

api: ServiceDef = is_prod
  ? base_api with { restart: `always` }
  : base_api with { environment: base_api.environment with { DEBUG: `true` } }

db: ServiceDef = {
  image: `postgres:16`,
  environment: {
    POSTGRES_PASSWORD: db_password,
    POSTGRES_DB: `app`,
  },
  restart: `always`,
}

compose: Compose = {
  version: `3.9`,
  services: { api, db },
  networks: {
    default: { driver: `bridge` },
  },
  volumes: {
    pgdata: { driver: `local` },
  },
}

pub main = || Emit::manifest({
  entries: [
    {
      path: Path::join([`docker-compose.yml`]),
      format: `yaml`,
      value: compose,
    },
  ]
})
```

## Output

```yaml
# docker-compose.yml (with COMPOSE_ENV=dev)
version: "3.9"
services:
  api:
    image: my-org/api:latest
    ports:
      - "8080:8080"
    environment:
      NODE_ENV: dev
      DB_HOST: db
      DB_PASSWORD: changeme
      DEBUG: "true"
    depends_on:
      - db
    restart: on-failure
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: changeme
      POSTGRES_DB: app
    restart: always
networks:
  default:
    driver: bridge
volumes:
  pgdata:
    driver: local
```

## Key concepts

- **`std::Env`** — reads environment variables at compile time into a typed schema. Optional fields use `??` for defaults.
- **Multi-file modules** — `types.rank` exports shared type definitions; this example uses the canonical absolute form `root::types`. In a normal project source tree, a nearby sibling import can also use `super::types`.
- **`with` patch** — `base_api with { restart: \`always\` }` merges without mutating `base_api`.
- **`Emit::manifest(...)`** — emits one or more named artifacts. The file path and format are part of the descriptor.

## Run it

```sh
COMPOSE_ENV=prod DB_PASSWORD=secret rank examples/docker-compose
```

---

## Dotenv Config


Read a project-local `.env` file with `File::Read`, decode scalar values at the boundary with `Decode<T>`, and reshape the result into a typed runtime config.

## Source

```dotenv title="examples/dotenv-config/.env"
APP_ENV=prod
PORT=9000
DEBUG=true
APP_NAME="Rank Docs"
```

```rank title="examples/dotenv-config/main.rank"
/// Reads a project-local dotenv file through File::Read with Decode<T>
/// at the flat text boundary and reshapes it into a typed runtime config.

use std::Decode
use std::File
use std::Path

AppEnv = `dev` | `prod`
Port = 8080 | 9000

DotenvConfig = Object {
  APP_ENV: AppEnv,
  PORT?: Decode<Port>,
  DEBUG?: Decode<bool>,
  APP_NAME: string,
  ...: string,
}

AppConfig = Object {
  name: string,
  env: AppEnv,
  port: number,
  debug: bool,
  source: Object {
    path: string,
    format: `dotenv`,
  },
}

response = File::Read<DotenvConfig> {
  path: Path::join([`.env`]),
  format: `dotenv`,
}

raw = response.body

config: AppConfig = {
  name: raw.APP_NAME,
  env: raw.APP_ENV,
  port: raw.PORT ?? 8080,
  debug: raw.DEBUG ?? false,
  source: {
    path: response.ctx.path,
    format: `dotenv`,
  },
}

pub main = || config
```

## Output

```json
{
  "name": "Rank Docs",
  "env": "prod",
  "port": 9000,
  "debug": true,
  "source": {
    "path": ".env",
    "format": "dotenv"
  }
}
```

## Key concepts

- **`format: dotenv`** — `File::Read` can decode `.env`-style flat text files as an explicit file dependency rather than ambient host environment.
- **Boundary decoding with `Decode<T>`** — `PORT?: Decode<Port>` and `DEBUG?: Decode<bool>` turn dotenv text into typed scalar values as the file is read.
- **Flat text model** — each dotenv entry stays one key/value text boundary; nested objects and lists are not decoded from a single entry.
- **`response.ctx`** — file provenance stays explicit, so the resulting config can still carry the source path and format.
- **Defaults after decode** — optional decoded fields combine cleanly with `??` once the boundary parsing has succeeded.

## Run it

```sh
rank examples/dotenv-config
```

---

## DynamoDB Report


Read seeded DynamoDB order items through the AWS provider and emit a static weekly sales report as JSON.

## Source

```rank title="examples/dynamodb-report/types.rank"
use aws::DynamoDB::{ Table }

pub OrderStatus = `paid` | `pending` | `refunded`

pub Region = `us` | `eu` | `apac`

pub Order = Object {
  reportId: string,
  orderId: string,
  customer: string,
  region: Region,
  status: OrderStatus,
  total: number,
}

pub OrdersTable = Table<Order, `reportId`, `orderId`>

pub RegionSummary = Object {
  region: Region,
  orders: number,
  revenue: number,
}

pub WeeklyReport = Object {
  reportId: string,
  totals: Object {
    totalOrders: number,
    grossRevenue: number,
    paidOrders: number,
    pendingOrders: number,
    refundedOrders: number,
  },
  byRegion: [RegionSummary],
  orders: [Order],
}
```

```rank title="examples/dynamodb-report/main.rank"
/// Reads seeded DynamoDB order items and emits a static report artifact.
/// Shows provider-backed reads plus pure collection transforms.

use aws::{ DynamoDB }
use std::Env
use std::Emit
use std::Path
use std::collections::{ count, filter, length, map, reduce }
use root::types::{ Order, OrdersTable, Region, RegionSummary, WeeklyReport }

SysEnv = Object {
  DYNAMODB_ENDPOINT?: string,
  ...: string,
}

{ DYNAMODB_ENDPOINT } = Env<SysEnv> {}

dynamodb_endpoint = DYNAMODB_ENDPOINT ?? `http://127.0.0.1:4566`
report_id = `weekly-2026-05-13`

dynamo_client: aws::DynamoDB::ClientConfig = DynamoDB::createClient({
  region: `us-east-1`,
  endpoint: dynamodb_endpoint,
  credentials: {
    accessKeyId: `test`,
    secretAccessKey: `test`,
  },
})

order_defaults: [Order] = [
  {
    reportId: report_id,
    orderId: `ord-1001`,
    customer: `Acme Co`,
    region: `us`,
    status: `paid`,
    total: 240,
  },
  {
    reportId: report_id,
    orderId: `ord-1002`,
    customer: `Globex`,
    region: `eu`,
    status: `paid`,
    total: 180,
  },
  {
    reportId: report_id,
    orderId: `ord-1003`,
    customer: `Initech`,
    region: `apac`,
    status: `pending`,
    total: 95,
  },
  {
    reportId: report_id,
    orderId: `ord-1004`,
    customer: `Umbrella`,
    region: `us`,
    status: `refunded`,
    total: -45,
  },
]

resolve_order = |fallback: Order| -> Order {
  result: aws::DynamoDB::ItemResult<OrdersTable> = aws::DynamoDB::Item<OrdersTable> {
    client: dynamo_client,
    tableName: `Orders`,
    key: {
      reportId: fallback.reportId,
      orderId: fallback.orderId,
    },
  }

  return result.item ?? fallback
}

orders: [Order] = order_defaults |> map(|fallback: Order| resolve_order(fallback))

revenue_for = |region: Region| -> number {
  return orders
    |> filter(|order: Order| order.region == region)
    |> reduce(0, |acc: number, order: Order| acc + order.total)
}

region_summary_for = |region: Region| -> RegionSummary {
  return {
    region: region,
    orders: count(orders, |order: Order| order.region == region),
    revenue: revenue_for(region),
  }
}

report: WeeklyReport = {
  reportId: report_id,
  totals: {
    totalOrders: length(orders),
    grossRevenue: orders |> reduce(0, |acc: number, order: Order| acc + order.total),
    paidOrders: count(orders, |order: Order| order.status == `paid`),
    pendingOrders: count(orders, |order: Order| order.status == `pending`),
    refundedOrders: count(orders, |order: Order| order.status == `refunded`),
  },
  byRegion: [
    region_summary_for(`us`),
    region_summary_for(`eu`),
    region_summary_for(`apac`),
  ],
  orders: orders,
}

pub main = || Emit::manifest({
  entries: [
    {
      path: Path::join([`reports`, `weekly-sales.json`]),
      format: `json`,
      value: report,
    },
  ]
})
```

## Output

```json
{
  "reportId": "weekly-2026-05-13",
  "totals": {
    "totalOrders": 4,
    "grossRevenue": 470,
    "paidOrders": 2,
    "pendingOrders": 1,
    "refundedOrders": 1
  },
  "byRegion": [
    { "region": "us", "orders": 2, "revenue": 195 },
    { "region": "eu", "orders": 1, "revenue": 180 },
    { "region": "apac", "orders": 1, "revenue": 95 }
  ]
}
```

## Run it

Start LocalStack from the example directory:

```sh
cd examples/dynamodb-report
docker compose up
```

Then run the Rank program from the workspace root:

```sh
npm run rank -- examples/dynamodb-report --file-root out/dynamodb-report
```

## Key concepts

- **`aws::DynamoDB::Item`** provides typed item reads from seeded DynamoDB data.
- **Pure collection transforms** turn fetched items into a static report with `count`, `filter`, `length`, and `reduce`.
- **Manifest emission** writes the derived report as a named JSON artifact.
- **LocalStack-backed data source** keeps the example runnable without touching real AWS infrastructure.

---

## Env Inputs


Read typed environment variables with literal unions, field-level sensitive schema annotations, `Decode<T>` boundary decoding, and environment-aware overrides.

## Source

```rank title="examples/env-inputs/main.rank"
/// Shows std::Env with explicit Decode<T> at the env boundary, field-level
/// sensitive schema annotations, defaults, and environment-specific overrides.

use std::Decode
use std::Env

AppEnv = `dev` | `staging` | `prod`
LogLevel = `debug` | `info` | `warn` | `error`
Port = 8080 | 8443 | 9000

SysEnv = Object {
  APP_ENV: AppEnv,
  PORT?: Decode<Port>,
  LOG_LEVEL?: LogLevel,
  @sensitive
  SECRET_KEY: string,
  ...: string,
}

AppConfig = Object {
  env: AppEnv,
  port: number,
  logLevel: LogLevel,
  debug: bool,
  baseUrl: string,
}

env = Env<SysEnv> {}

port: number = env.PORT ?? 8080

base_config: AppConfig = {
  env: env.APP_ENV,
  port: port,
  logLevel: env.LOG_LEVEL ?? (env.APP_ENV == `prod` ? `warn` : `debug`),
  debug: env.APP_ENV == `dev`,
  baseUrl: `http://localhost:${port}`,
}

config: AppConfig = env.APP_ENV == `prod`
  ? base_config with { baseUrl: `https://api.example.com` }
  : base_config

pub main = || config
```

## Output

```json
// APP_ENV=prod PORT=8443 LOG_LEVEL=warn SECRET_KEY=abc123
{
  "env": "prod",
  "port": 8443,
  "logLevel": "warn",
  "debug": false,
  "baseUrl": "https://api.example.com"
}
```

## Key concepts

- **Literal env schema** — `APP_ENV` and `LOG_LEVEL` are constrained to finite unions before the rest of the program runs, and `PORT` is decoded to a numeric union at the boundary.
- **Required vs optional vars** — `APP_ENV` and `SECRET_KEY` must be present, while `PORT` and `LOG_LEVEL` can safely fall back.
- **Field-level sensitive schema annotation** — `SECRET_KEY` carries `@sensitive` on the type field itself, so the env boundary can redact the secret without needing a separate sensitive binding.
- **`Decode<T>` + `??`** — `PORT?: Decode<Port>` turns host text into a typed numeric value at the env boundary, and `??` supplies the default when the variable is absent.
- **`with` for environment-specific shape** — the production branch overrides only `baseUrl`, leaving the rest of the typed object unchanged.

## Run it

```sh
APP_ENV=dev SECRET_KEY=mysecret rank examples/env-inputs
APP_ENV=prod PORT=8443 LOG_LEVEL=warn SECRET_KEY=mysecret rank examples/env-inputs
```

---

## Faker Dataset


Generate a deterministic set of user records with correlated person and location fields, using all of the Faker provider's generator kinds.

## Source

```toml title="examples/faker-dataset/rank.toml"
manifestVersion = 1

[package]
name = "faker-dataset"
version = "0.1.0"
source = "."

[providers]
faker = { registry = "npm", package = "@rank-lang/plugin-faker", version = "0.1.0" }
```

```rank title="examples/faker-dataset/main.rank"
/// Generates a deterministic seed dataset of users using the Faker provider.
/// Shows correlated Person and Location projections, all generator kinds
/// (UUID, Int, Boolean, DateTime, Person, Location), and multi-record
/// collection generation with Emit::manifest.

use faker::{ Boolean, DateTime, Generate, Int, Location, Person, UUID }
use faker::types::{ Spec }
use std::Time
use std::list::{ range }
use std::collections::{ map }
use std::Emit
use std::Path

/// --- Types ---

Address = Object {
  street: string,
  city: string,
  country: string,
}

User = Object {
  id: string,
  firstName: string,
  lastName: string,
  email: string,
  age: number,
  address: Address,
  role: string,
  active: bool,
  createdAt: Time::Instant,
  score: number,
}

/// --- Generator descriptors ---

seed = 1

refDate: Time::Instant = Time::parse(`2025-01-01T00:00:00Z`, { format: `RFC3339` })

person = Person { sex: `female` }
location = Location {}

userSpec: Spec<User> = {
  id: UUID {},
  firstName: person.firstName,
  lastName: person.lastName,
  email: person.email,
  age: Int { min: 18, max: 65 },
  address: {
    street: location.street,
    city: location.city,
    country: location.country,
  },
  role: `member`,
  active: Boolean { probability: 0.8 },
  createdAt: DateTime {
    past: { years: 3 },
  },
  score: Int { min: 0, max: 1000 },
}

/// --- Generate 20 users ---

count = 20

users: [User] = range(count)
  |> map(|_, ctx| Generate<User> {
       spec: userSpec,
       seed,
       itemKey: ctx.index,
       locale: `en_US`,
       refDate,
     })

/// --- Emit ---

pub main = || Emit::manifest({
  entries: [
    {
      path: Path::join([`users.json`]),
      format: `json`,
      value: users,
    },
  ]
})
```

## Output

```json
// users.json (first two records shown)
[
  {
    "id": "a3f1c2d4-...",
    "firstName": "Sophia",
    "lastName": "Martinez",
    "email": "Sophia.Martinez@example.com",
    "age": 34,
    "address": {
      "street": "742 Evergreen Terrace",
      "city": "Springfield",
      "country": "United States"
    },
    "role": "member",
    "active": true,
    "createdAt": { "epochMillis": 1672531200000, "offsetMinutes": 0 },
    "score": 812
  },
  {
    "id": "b7e8d9f0-...",
    "firstName": "Olivia",
    "lastName": "Chen",
    "email": "Olivia.Chen@example.com",
    "age": 27,
    "address": {
      "street": "18 Oak Lane",
      "city": "Portland",
      "country": "United States"
    },
    "role": "member",
    "active": false,
    "createdAt": { "epochMillis": 1698796800000, "offsetMinutes": 0 },
    "score": 441
  }
]
```

## Key concepts

- **`Person` projections** — `person.firstName`, `person.lastName`, `person.email`, `person.age`, `person.address` are correlated: they all come from the same generated person, so the email matches the name on every record.
- **`Location` projections** — `location.street`, `location.city`, `location.country` are similarly correlated from a single generated location.
- **`Spec<T>`** — the spec mirrors the shape of `User`. Literal values (`role: \`member\``) are passed through unchanged; generator descriptors are evaluated per record.
- **`seed` + `itemKey`** — `seed` fixes the base RNG; `itemKey: ctx.index` derives a distinct sub-stream per record, so record 0 and record 1 are always different but always the same across runs.
- **`refDate`** — anchors relative date generators like `DateTime { past: { years: 3 } }` to a fixed point in time, keeping the dataset stable even as the current date changes.
- **`Boolean { probability: 0.8 }`** — approximately 80% of users will have `active: true`.

## Run it

```sh
rank examples/faker-dataset --file-root out/
```

Writes `out/users.json`. Requires the `@rank-lang/plugin-faker` package — see the [Faker Provider](../faker-provider) docs for installation.

---

## Feature Flag Matrix


Generate per-plan feature flag bundles and a flattened environment-by-plan matrix from one typed model.

## Source

```rank title="examples/feature-flag-matrix/types.rank"
pub Environment = `dev` | `staging` | `prod`

pub Plan = `free` | `pro` | `enterprise`

pub FlagState = `enabled` | `disabled`

pub FeatureFlags = Object {
  auditLogs: FlagState,
  sso: FlagState,
  ledgerExport: FlagState,
  prioritySupport: FlagState,
}

pub FlagMatrixEntry = Object {
  environment: Environment,
  plan: Plan,
  flags: FeatureFlags,
}
```

```rank title="examples/feature-flag-matrix/main.rank"
/// Generates per-plan feature flag configs and a flattened matrix view.
/// Shows typed environment/plan combinations and multi-file emission.

use std::Emit
use std::Path
use std::collections::{ flatMap, map }
use root::types::{ Environment, FeatureFlags, FlagMatrixEntry, Plan }

environments: [Environment] = [`dev`, `staging`, `prod`]
plans: [Plan] = [`free`, `pro`, `enterprise`]

base_flags_for = |plan: Plan| -> FeatureFlags {
  return match plan {
    `free` => {
      auditLogs: `disabled`,
      sso: `disabled`,
      ledgerExport: `disabled`,
      prioritySupport: `disabled`,
    },
    `pro` => {
      auditLogs: `enabled`,
      sso: `disabled`,
      ledgerExport: `enabled`,
      prioritySupport: `disabled`,
    },
    `enterprise` => {
      auditLogs: `enabled`,
      sso: `enabled`,
      ledgerExport: `enabled`,
      prioritySupport: `enabled`,
    },
  }
}

flags_for = |environment: Environment, plan: Plan| -> FeatureFlags {
  base = base_flags_for(plan)

  return match environment {
    `dev` => base with {
      auditLogs: `enabled`,
      ledgerExport: `enabled`,
    },
    `staging` => base,
    `prod` => base,
  }
}

entry_for = |environment: Environment, plan: Plan| -> FlagMatrixEntry {
  return {
    environment: environment,
    plan: plan,
    flags: flags_for(environment, plan),
  }
}

matrix_entries = environments
  |> flatMap(|environment: Environment| plans |> map(|plan: Plan| entry_for(environment, plan)))

plan_bundle_for = |plan: Plan| {
  return {
    plan: plan,
    environments: environments |> map(|environment: Environment| {
      environment: environment,
      flags: flags_for(environment, plan),
    }),
  }
}

pub main = || Emit::manifest({
  entries: [
    {
      path: Path::join([`flags`, `matrix.json`]),
      format: `json`,
      value: matrix_entries,
    },
    {
      path: Path::join([`flags`, `free.json`]),
      format: `json`,
      value: plan_bundle_for(`free`),
    },
    {
      path: Path::join([`flags`, `pro.json`]),
      format: `json`,
      value: plan_bundle_for(`pro`),
    },
    {
      path: Path::join([`flags`, `enterprise.json`]),
      format: `json`,
      value: plan_bundle_for(`enterprise`),
    },
  ]
})
```

## Output

Running the example with `--file-root` writes:

- `flags/matrix.json`
- `flags/free.json`
- `flags/pro.json`
- `flags/enterprise.json`

## Run it

```sh
npm run rank -- examples/feature-flag-matrix --file-root out/feature-flag-matrix
```

## Key concepts

- Typed environment and plan dimensions become a complete matrix with `flatMap`.
- A shared feature model emits both per-plan bundles and a flattened aggregate view.
- `with` lets one environment patch a base plan config without duplicating the whole object.

---

## File-driven Config


Load a YAML config file at compile time, validate it against a typed schema, and reshape it into a deployment manifest.

## Source

```yaml title="examples/file-driven-config/input.yaml"
services:
  - name: api
    port: 8080
    enabled: true
  - name: worker
    port: 9090
    enabled: true
  - name: admin
    port: 7070
    enabled: false

database:
  host: db.internal
  port: 5432
  name: app
```

```rank title="examples/file-driven-config/main.rank"
/// Reads a YAML config file at compile time and reshapes it into a
/// deployment manifest. Shows File::Read with a typed schema and
/// stdlib transforms on the loaded data.

use std::File
use std::Path
use std::collections::{ filter, map }
use std::Emit

ServiceEntry = Object {
  name: string,
  port: number,
  enabled: bool,
}

InputConfig = Object {
  services: [ServiceEntry],
  database: Object {
    host: string,
    port: number,
    name: string,
  },
}

DeployedService = Object {
  name: string,
  port: number,
  address: string,
}

response = File::Read<InputConfig> {
  path: Path::join([`input.yaml`]),
  format: `yaml`,
}

input = response.body

active_services: [DeployedService] = input.services
  |> filter(|svc: ServiceEntry| svc.enabled)
  |> map(|svc: ServiceEntry| -> DeployedService {
       return {
         name: svc.name,
         port: svc.port,
         address: `${svc.name}.internal:${svc.port}`,
       }
     })

manifest = {
  services: active_services,
  database: input.database,
}

pub main = || Emit::manifest({
  entries: [
    {
      path: Path::join([`manifest.json`]),
      format: `json`,
      value: manifest,
    },
    {
      path: Path::join([`manifest.yaml`]),
      format: `yaml`,
      value: manifest,
    },
  ]
})
```

## Output

```json
// manifest.json
{
  "services": [
    { "name": "api", "port": 8080, "address": "api.internal:8080" },
    { "name": "worker", "port": 9090, "address": "worker.internal:9090" }
  ],
  "database": {
    "host": "db.internal",
    "port": 5432,
    "name": "app"
  }
}
```

The `admin` service is excluded because `enabled: false`.
The same manifest is also emitted as `manifest.yaml`.

## Key concepts

- **`File::Read<T>`** — reads and parses a file into the typed schema `T`. A schema mismatch is a compile-time error.
- **`response.body`** — the parsed, type-checked content of the file.
- **`response.ctx`** — metadata: `{ path, format }`.
- **`Path::join`** — constructs a `Path::RelativePath` from path segments. Paths are resolved relative to the project source root.
- **`Emit::manifest(...)`** — emits both JSON and YAML artifacts from the same typed manifest descriptor.
- **Filter then map** — the pipe chain keeps only enabled services and builds the `address` field, leaving the database block untouched.

## Run it

```sh
rank examples/file-driven-config
```

---

## Functions and Lifting


First-class functions, object and list lifting, and non-destructive override with `with`.

## Source

```rank title="examples/functions-and-lifting/main.rank"
/// Demonstrates first-class functions, automatic lifting over lists and objects,
/// zipped list lifting, and the `with` patch operator.

shift_port = |delta: number, port: number| -> number {
  return port + delta
}

scale = |factor: number, value: number| -> number {
  return value * factor
}

add = |left: number, right: number| -> number {
  return left + right
}

ports = {
  api: 8080,
  worker: 9090,
  admin: 7070,
}

replica_counts = {
  api: 3,
  worker: 2,
  admin: 1,
}

base_ports = [8080, 8081, 8082]
rollout_offsets = [0, 100, 200]

base_service = {
  port: 3000,
  replicas: 1,
  debug: false,
}

dev_override = base_service with {
  debug: true,
}

prod_override = base_service with {
  replicas: 5,
}

pub main = || {
  shifted_ports: shift_port(10000, ports),
  scaled_replicas: scale(3, replica_counts),
  canary_ports: add(base_ports, rollout_offsets),
  dev: dev_override,
  prod: prod_override,
}
```

## Output

```json
{
  "shifted_ports": {
    "api": 18080,
    "worker": 19090,
    "admin": 17070
  },
  "scaled_replicas": {
    "api": 9,
    "worker": 6,
    "admin": 3
  },
  "canary_ports": [8080, 8181, 8282],
  "dev": {
    "port": 3000,
    "replicas": 1,
    "debug": true
  },
  "prod": {
    "port": 3000,
    "replicas": 5,
    "debug": false
  }
}
```

## Key concepts

- **Object lifting** — `shift_port(10000, ports)` applies the same scalar function to every field of the object. No explicit traversal code is needed.
- **Broadcast over structured values** — `scale(3, replica_counts)` keeps the scalar `3` fixed while lifting across the object on the right.
- **Zipped list lifting** — `add(base_ports, rollout_offsets)` aligns both lists by position and applies `add` element-by-element.
- **`with` patch** — `base_service with { debug: true }` produces a new object identical to `base_service` except for the overridden fields. The original is never mutated.

## Run it

```sh
rank examples/functions-and-lifting
```

---

## GitHub Actions


Generate a CI workflow that tests against multiple Node.js versions using lifting over a version list.

## Source

```rank title="examples/github-actions/main.rank"
/// Generates a GitHub Actions CI workflow.
/// Shows string template composition, lifting map over a job matrix,
/// and conditional step inclusion via ternary expressions.

use std::collections::{ map }
use std::Emit
use std::Path

Step = Object {
  name: string,
  uses?: string,
  run?: string,
  with?: Object { ...: string },
  env?: Object { ...: string },
}

Job = Object {
  name: string,
  `runs-on`: string,
  steps: [Step],
}

Workflow = Object {
  name: string,
  on: Object {
    push: Object { branches: [string] },
    pull_request: Object { branches: [string] },
  },
  jobs: Object { ...: Job },
}

node_versions: [string] = [`18`, `20`, `22`]

checkout_step: Step = {
  name: `Checkout`,
  uses: `actions/checkout@v4`,
}

setup_node = |version: string| -> Step {
  return {
    name: `Setup Node ${version}`,
    uses: `actions/setup-node@v4`,
    with: { `node-version`: version },
  }
}

install_step: Step = {
  name: `Install dependencies`,
  run: `npm ci`,
}

test_step: Step = {
  name: `Run tests`,
  run: `npm test`,
}

build_job = |version: string| -> Job {
  return {
    name: `build-node-${version}`,
    `runs-on`: `ubuntu-latest`,
    steps: [
      checkout_step,
      setup_node(version),
      install_step,
      test_step,
    ],
  }
}

jobs: [Job] = node_versions |> map(|v: string| build_job(v))

workflow: Workflow = {
  name: `CI`,
  on: {
    push: { branches: [`main`] },
    pull_request: { branches: [`main`] },
  },
  jobs: {
    `build-18`: jobs[0],
    `build-20`: jobs[1],
    `build-22`: jobs[2],
  },
}

pub main = || Emit::manifest({
  entries: [
    {
      path: Path::join([`.github`, `workflows`, `ci.yml`]),
      format: `yaml`,
      value: workflow,
    },
  ]
})
```

## Output

```yaml
# .github/workflows/ci.yml
name: CI
on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
jobs:
  build-18:
    name: build-node-18
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Node 18
        uses: actions/setup-node@v4
        with:
          node-version: "18"
      - name: Install dependencies
        run: npm ci
      - name: Run tests
        run: npm test
  build-20:
    # ... same pattern for 20 and 22
```

## Key concepts

- **`map` over a list** — `node_versions |> map(|v| build_job(v))` produces one `Job` per version with no boilerplate.
- **String interpolation in keys** — backtick strings like `` `build-node-${version}` `` work in field names and values.
- **Quoted field names** — `` `runs-on` `` uses a backtick string as a field name to handle the hyphen.
- **`Path::join`** — constructs the nested output path `.github/workflows/ci.yml` safely.

## Run it

```sh
rank examples/github-actions
```

---

## GitLab CI


Generate a `.gitlab-ci.yml` pipeline with reusable job templates defined as functions and rule-based conditional execution.

## Source

```rank title="examples/gitlab-ci/main.rank"
/// Generates a GitLab CI pipeline configuration.
/// Shows reusable job templates defined as functions, stage ordering,
/// and rule-based conditional job execution.

use std::Emit
use std::Path

Rule = Object {
  `if`: string,
}

Job = Object {
  stage: string,
  image: string,
  script: [string],
  rules?: [Rule],
  needs?: [string],
  artifacts?: Object {
    paths: [string],
    expire_in: string,
  },
}

Pipeline = Object {
  stages: [string],
  variables: Object { ...: string },
  ...: Job,
}

stages: [string] = [`build`, `test`, `deploy`]

mr_only: Rule = { `if`: `$CI_PIPELINE_SOURCE == "merge_request_event"` }
main_only: Rule = { `if`: `$CI_COMMIT_BRANCH == "main"` }
always: Rule = { `if`: `$CI_PIPELINE_SOURCE != ""` }

node_job = |stage: string, script: [string]| -> Job {
  return {
    stage: stage,
    image: `node:20-alpine`,
    script: script,
  }
}

build: Job = node_job(`build`, [`npm ci`, `npm run build`]) with {
  artifacts: {
    paths: [`dist/`],
    expire_in: `1 hour`,
  },
  rules: [always],
}

test: Job = node_job(`test`, [`npm ci`, `npm test`]) with {
  rules: [always],
  needs: [`build`],
}

deploy_staging: Job = node_job(`deploy`, [`./scripts/deploy.sh staging`]) with {
  rules: [mr_only],
  needs: [`test`],
}

deploy_prod: Job = node_job(`deploy`, [`./scripts/deploy.sh production`]) with {
  rules: [main_only],
  needs: [`test`],
}

pipeline: Pipeline = {
  stages: stages,
  variables: {
    DOCKER_DRIVER: `overlay2`,
    NODE_ENV: `ci`,
  },
  build: build,
  test: test,
  `deploy:staging`: deploy_staging,
  `deploy:prod`: deploy_prod,
}

pub main = || Emit::manifest({
  entries: [
    {
      path: Path::join([`.gitlab-ci.yml`]),
      format: `yaml`,
      value: pipeline,
    },
  ]
})
```

## Output

```yaml
# .gitlab-ci.yml
stages:
  - build
  - test
  - deploy
variables:
  DOCKER_DRIVER: overlay2
  NODE_ENV: ci
build:
  stage: build
  image: node:20-alpine
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 hour
  rules:
    - if: '$CI_PIPELINE_SOURCE != ""'
test:
  stage: test
  image: node:20-alpine
  script:
    - npm ci
    - npm test
  needs:
    - build
  rules:
    - if: '$CI_PIPELINE_SOURCE != ""'
deploy:staging:
  stage: deploy
  image: node:20-alpine
  script:
    - ./scripts/deploy.sh staging
  needs:
    - test
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
deploy:prod:
  stage: deploy
  image: node:20-alpine
  script:
    - ./scripts/deploy.sh production
  needs:
    - test
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
```

## Key concepts

- **Function-as-template** — `node_job` returns a base `Job` that callers customise with `with`, avoiding repetition while keeping each job explicit.
- **Open object type** — `Pipeline = Object { stages: ..., ...: Job }` allows arbitrary additional fields (the job entries) beyond the declared ones.
- **`with` for optional fields** — adding `artifacts` or `rules` via `with` keeps the base template minimal and each job self-describing.

## Run it

```sh
rank examples/gitlab-ci
```

---

## Hello Config


A compact Rank program that still shows validation and composition, not just object literals.

## Source

```rank title="examples/hello-config/main.rank"
/// A small but realistic configuration object demonstrating
/// type aliases, constraints, and non-destructive overrides with `with`.

Mode = `dev` | `prod`

AppConfig = Object {
  name: string,
  host: string,
  port: number,
  debug: bool,
}

mode: Mode = `dev`

@constraint(cond: |self| self >= 1 && self <= 65535)
port = mode == `prod` ? 443 : 8080

base_config = {
  name: `my-app`,
  host: `localhost`,
  port: 80,
  debug: false,
}

config: AppConfig = base_config with {
  port: port,
  debug: mode == `dev`,
}

pub main = || config
```

## Output

```json
{
  "name": "my-app",
  "host": "localhost",
  "port": 8080,
  "debug": true
}
```

## Key concepts

- **Literal unions** — `Mode = \`dev\` | \`prod\`` keeps configuration modes explicit and finite.
- **`@constraint`** — the `port` binding fails fast if the computed value ever falls outside the valid port range.
- **`with`** — `base_config with { ... }` expresses overrides without mutating the original object.
- **Type annotations** — `config: AppConfig = ...` checks the final composed value against the named output type.

## Run it

```sh
rank examples/hello-config
```

---

## HTTP Fetch


Fetch external data from a real API at compile time, validate the response against a typed schema, and transform it into a smaller artifact.

## Source

```rank title="examples/http-fetch/main.rank"
/// Fetches a real Lorem API article at compile time and transforms
/// the response into a smaller summary artifact.
/// Shows HTTP::Fetch with a typed response schema, cacheKey for determinism,
/// and accessing both response.body and response.ctx metadata.

use std::HTTP
use std::Emit
use std::Path

Author = Object {
  id: string,
  name: string,
  avatar: string,
  email: string,
}

Article = Object {
  slug: string,
  title: string,
  subtitle: string,
  image: string,
  author: Author,
  content: string,
  dateCreated: string,
}

ArticleSummary = Object {
  slug: string,
  title: string,
  subtitle: string,
  author: Object {
    name: string,
    email: string,
  },
  coverImage: string,
  publishedAt: string,
  status: number,
  source: string,
}

response = HTTP::Fetch<Article> {
  url: `https://lorem-api.com/api/article/rank-http-fetch`,
  method: `GET`,
  headers: {
    Accept: `application/json`,
  },
  cacheKey: `lorem-article-rank-http-fetch-v1`,
}

article = response.body

summary: ArticleSummary = {
  slug: article.slug,
  title: article.title,
  subtitle: article.subtitle,
  author: {
    name: article.author.name,
    email: article.author.email,
  },
  coverImage: article.image,
  publishedAt: article.dateCreated,
  status: response.ctx.status,
  source: response.ctx.cacheKey,
}

pub main = || Emit::manifest({
  entries: [
    {
      path: Path::join([`article-summary.json`]),
      format: `json`,
      value: summary,
    },
  ]
})
```

## Output

```json
// article-summary.json
{
  "slug": "rank-http-fetch",
  "title": "Adeptio abeo cervus voluptatum delego sequi ducimus virga.",
  "subtitle": "Rerum atqui rerum et.",
  "author": {
    "name": "Shannon McDermott V",
    "email": "Fae.Gerhold@hotmail.com"
  },
  "coverImage": "https://picsum.photos/seed/RA7K2McSOQ/3074/340?blur=1",
  "publishedAt": "2020-10-01T08:13:16.355Z",
  "status": 200,
  "source": "lorem-article-rank-http-fetch-v1"
}
```

## Key concepts

- **`HTTP::Fetch<T>`** — issues an HTTP request and validates the parsed response body against `T`. A schema mismatch is a compile-time error.
- **Real endpoint** — this example uses Lorem API's article endpoint at `https://lorem-api.com/api/article/{slug}` rather than a placeholder host.
- **`cacheKey`** — required for determinism. Rank stores the fetched response under this key; the same key always returns the same data within a build.
- **`response.body`** — the type-checked response body.
- **`response.ctx`** — request metadata: `{ status, cacheKey, headers }`.
- **Compile-time fetch** — the request runs when Rank evaluates the program, not at application startup. The result is baked into the generated artifact.

## Run it

```sh
rank examples/http-fetch/main.rank --http-cache examples/http-fetch/http-cache.json
rank examples/http-fetch/main.rank --http-cache examples/http-fetch/http-cache.json --file-root out/http-fetch
```

:::note
This example includes a checked-in snapshot at `examples/http-fetch/http-cache.json`. The current CLI evaluates `HTTP::Fetch` from snapshot data, so use `--http-cache` to replay the real Lorem API response deterministically in local runs and CI.
:::

---

## HTTP Plus Files Bundle


Combine a local YAML config file with an HTTP fetch and emit both a JSON bundle and route metadata.

## Source

```yaml title="examples/http-plus-files-bundle/input.yaml"
site:
  name: Rank Launchpad
  themeColor: tide
  navItems:
    - Overview
    - Docs
    - Pricing

landing:
  heroTitle: Ship configuration as code
  featuredArticleSlug: rank-http-fetch
```

```rank title="examples/http-plus-files-bundle/main.rank"
/// Combines a local YAML config file with an HTTP fetch and emits a bundle.
/// Shows File::Read and HTTP::Fetch working together in one program.

use std::Emit
use std::File
use std::HTTP
use std::Path

InputConfig = Object {
  site: Object {
    name: string,
    themeColor: string,
    navItems: [string],
  },
  landing: Object {
    heroTitle: string,
    featuredArticleSlug: string,
  },
}

Author = Object {
  id: string,
  name: string,
  avatar: string,
  email: string,
}

Article = Object {
  slug: string,
  title: string,
  subtitle: string,
  image: string,
  author: Author,
  dateCreated: string,
  content: string,
}

input_result = File::Read<InputConfig> {
  path: Path::join([`input.yaml`]),
  format: `yaml`,
}

input = input_result.body

article_result = HTTP::Fetch<Article> {
  url: `https://lorem-api.com/api/article/rank-http-fetch`,
  method: `GET`,
  headers: {
    Accept: `application/json`,
  },
  cacheKey: `http-plus-files-bundle-rank-http-fetch-v1`,
}

article = article_result.body

bundle = {
  site: {
    name: input.site.name,
    themeColor: input.site.themeColor,
    heroTitle: input.landing.heroTitle,
    navItems: input.site.navItems,
  },
  featuredArticle: {
    slug: article.slug,
    title: article.title,
    subtitle: article.subtitle,
    author: article.author.name,
    publishedAt: article.dateCreated,
  },
  source: {
    articleCacheKey: article_result.ctx.cacheKey,
    status: article_result.ctx.status,
  },
}

routes = {
  siteName: input.site.name,
  routes: [
    {
      path: `/`,
      title: input.landing.heroTitle,
    },
    {
      path: `/articles/${article.slug}`,
      title: article.title,
    },
  ],
}

pub main = || Emit::manifest({
  entries: [
    {
      path: Path::join([`bundle`, `site-bundle.json`]),
      format: `json`,
      value: bundle,
    },
    {
      path: Path::join([`bundle`, `routes.yaml`]),
      format: `yaml`,
      value: routes,
    },
  ]
})
```

## Output

Running the example with `--file-root` writes:

- `bundle/site-bundle.json`
- `bundle/routes.yaml`

## Run it

```sh
npm run rank -- examples/http-plus-files-bundle --file-root out/http-plus-files-bundle
```

## Key concepts

- `File::Read` can load local structured input while `HTTP::Fetch` contributes remote typed data in the same program.
- `cacheKey` keeps the HTTP side deterministic for repeated evaluations.
- Response metadata from `response.ctx` can flow directly into emitted artifacts.

---

## Examples


Runnable Rank programs organized by theme. Each example lives in the [`examples/`](https://github.com/rank-lang/rank/tree/main/examples) directory of the repository.

Use this page when you want runnable reference programs for typed configuration, provider-backed reads and writes, external inputs, manifests, and HTTP workflows.

If you want the fastest language tour, start with [Hello Config](./hello-config.mdx), then [Functions and Lifting](./functions-and-lifting.mdx), then [Pipes and Collections](./pipes-and-collections.mdx), and then [Env Inputs](./env-inputs.mdx).

## Language features

| Example | What it shows |
|---------|--------------|
| [Hello Config](./hello-config) | Type aliases, literal unions, `@constraint`, `with`, `pub main` |
| [Types and Generics](./types-and-generics) | Type aliases, constrained/defaulted generics, utility types, field annotations, `match` exhaustiveness |
| [Functions and Lifting](./functions-and-lifting) | Named functions, object lifting, zipped list lifting, `with` patch |
| [Pipes and Collections](./pipes-and-collections) | `map`, `filter`, `reduce`, `groupBy`, `sortBy`, pipe operator `|>` |

## Platform manifests and CI/CD

| Example | What it shows |
|---------|--------------|
| [Kubernetes App](./kubernetes-app) | One typed app definition emitting Deployment, Service, ConfigMap, Ingress, and HPA YAML |
| [Service Catalog](./service-catalog) | One typed service list emitting service summary, CI matrix, public endpoints, Compose, and deployment metadata |
| [Static Site Deploy Plan](./static-site-deploy-plan) | Typed pages and redirects emitting upload metadata, redirect rules, and deploy planning artifacts |
| [Docker Compose](./docker-compose) | Typed service definitions, `Env` inputs, dev/prod overrides, `Emit::manifest(...)` |
| [GitHub Actions](./github-actions) | Workflow YAML generation, lifting over a node version matrix, `Emit::manifest(...)` |
| [GitLab CI](./gitlab-ci) | Pipeline YAML, reusable job templates as functions, rule-based conditions |

## Data generation and multi-environment

| Example | What it shows |
|---------|--------------|
| [Test Fixtures](./test-fixtures) | Faker provider, `range` + `map` to generate N records, deterministic seeds |
| [Faker Dataset](./faker-dataset) | Correlated `Person`/`Location` projections, all generator kinds, `refDate` anchoring |
| [Multi-env App](./multi-env-app) | `Env` input, base + environment-specific `with` overrides, multi-file modules |
| [Feature Flag Matrix](./feature-flag-matrix) | Typed environment and plan combinations emitting a matrix plus per-plan flag bundles |
| [Tenant Config Generator](./tenant-config-generator) | One tenant list emitting per-tenant runtime configs and a shared tenant index |

## External data sources

| Example | What it shows |
|---------|--------------|
| [Env Inputs](./env-inputs) | `std::Env` typed schema, field-level `@sensitive`, `Decode<T>` at the env boundary, defaults, `with` |
| [Dotenv Config](./dotenv-config) | `File::Read` with `format: dotenv`, boundary `Decode<T>`, typed defaults, and explicit file provenance |
| [File-driven Config](./file-driven-config) | `File::Read` YAML loading, typed schema, reshaping with stdlib |
| [HTTP Fetch](./http-fetch) | `HTTP::Fetch` with `cacheKey`, typed response schema, transform to manifest |
| [HTTP Plus Files Bundle](./http-plus-files-bundle) | Combine a local YAML file and an HTTP fetch into one bundled JSON and YAML output |
| [Secrets-Backed Config](./secrets-backed-config) | `aws::SecretsManager::Secret<T>`, `RANK_ENV`, base + secret merge, LocalStack-backed provider flow |
| [LocalStack Bootstrap](./localstack-bootstrap) | `Mutation::plan`, `aws::DynamoDB::Put`, `aws::S3::Put`, and LocalStack-backed resource seeding |
| [DynamoDB Report](./dynamodb-report) | Typed DynamoDB item reads, collection reductions, and a static JSON report artifact |
| [Provider Comparison](./provider-comparison) | Normalize environment, file, HTTP, and S3 inputs into one shared output schema |

## HTTP server

| Example | What it shows |
|---------|--------------|
| [S3 Logs](./s3-logs) | `rank serve`, `aws::S3::Object<T>`, `parse` string patterns, LocalStack-backed log inspection |
| [Serve — Docker](./serve-docker) | `rank serve`, `HTTP::Route`, `pub config`, containerized deployment |
| [Serve — Lambda](./serve-lambda) | Lambda Web Adapter, `READINESS_CHECK_PATH`, same app code locally and on Lambda |

---

## Kubernetes App


Generate a small Kubernetes application bundle from one typed service definition. This example emits a Deployment, Service, ConfigMap, Ingress, and HorizontalPodAutoscaler as separate YAML files.

## Source

```rank title="examples/kubernetes-app/types.rank"
use std::collections::{ length }

pub Environment = `dev` | `staging` | `prod`

pub LogLevel = `debug` | `info` | `warn` | `error`

pub FeatureFlag = `enabled` | `disabled`

pub AppRuntimeConfig = Object {
  APP_ENV: Environment,
  LOG_LEVEL: LogLevel,
  FEATURE_LEDGER_EXPORT: FeatureFlag,
  JVM_OPTS: string,
}

pub AppSpec = Object {
  @constraint(cond: |self| length(self) > 0)
  name: string,
  @constraint(cond: |self| length(self) > 0)
  namespace: string,
  @constraint(cond: |self| length(self) > 0)
  image: string,
  @constraint(cond: |self| self >= 1 && self <= 65535)
  containerPort: number,
  @constraint(cond: |self| self >= 1 && self <= 65535)
  servicePort: number,
  @constraint(cond: |self| length(self) > 0)
  host: string,
  @constraint(cond: |self| self >= 1)
  minReplicas: number,
  @constraint(cond: |self| self >= 1)
  maxReplicas: number,
  @constraint(cond: |self| self >= 1 && self <= 100)
  cpuTargetUtilization: number,
  env: AppRuntimeConfig,
}

pub LabelMap = Object {
  ...: string,
}

pub Metadata = Object {
  name: string,
  namespace?: string,
  labels?: LabelMap,
  annotations?: LabelMap,
}

pub LabelSelector = Object {
  matchLabels: LabelMap,
}

pub ConfigMapEnvSource = Object {
  configMapRef: Object {
    name: string,
  },
}

pub ContainerPort = Object {
  containerPort: number,
}

pub Container = Object {
  name: string,
  image: string,
  ports: [ContainerPort],
  envFrom?: [ConfigMapEnvSource],
}

pub PodSpec = Object {
  containers: [Container],
}

pub PodTemplate = Object {
  metadata: Object {
    labels: LabelMap,
  },
  spec: PodSpec,
}

pub DeploymentSpec = Object {
  replicas: number,
  selector: LabelSelector,
  template: PodTemplate,
}

pub Deployment = Object {
  apiVersion: `apps/v1`,
  kind: `Deployment`,
  metadata: Metadata,
  spec: DeploymentSpec,
}

pub ServicePort = Object {
  port: number,
  targetPort: number,
}

pub ServiceSpec = Object {
  type?: `ClusterIP` | `LoadBalancer`,
  selector: LabelMap,
  ports: [ServicePort],
}

pub Service = Object {
  apiVersion: `v1`,
  kind: `Service`,
  metadata: Metadata,
  spec: ServiceSpec,
}

pub ConfigMap = Object {
  apiVersion: `v1`,
  kind: `ConfigMap`,
  metadata: Metadata,
  data: Object {
    ...: string,
  },
}

pub IngressServiceBackend = Object {
  name: string,
  port: Object {
    number: number,
  },
}

pub IngressBackend = Object {
  service: IngressServiceBackend,
}

pub HTTPIngressPath = Object {
  path: string,
  pathType: `Prefix` | `Exact`,
  backend: IngressBackend,
}

pub HTTPIngressRule = Object {
  paths: [HTTPIngressPath],
}

pub IngressRule = Object {
  host: string,
  http: HTTPIngressRule,
}

pub IngressSpec = Object {
  ingressClassName: string,
  rules: [IngressRule],
}

pub Ingress = Object {
  apiVersion: `networking.k8s.io/v1`,
  kind: `Ingress`,
  metadata: Metadata,
  spec: IngressSpec,
}

pub CpuMetricTarget = Object {
  type: `Utilization`,
  averageUtilization: number,
}

pub ResourceMetricSource = Object {
  name: `cpu`,
  target: CpuMetricTarget,
}

pub MetricSpec = Object {
  type: `Resource`,
  resource: ResourceMetricSource,
}

pub ScaleTargetRef = Object {
  apiVersion: `apps/v1`,
  kind: `Deployment`,
  name: string,
}

pub HorizontalPodAutoscalerSpec = Object {
  scaleTargetRef: ScaleTargetRef,
  minReplicas: number,
  maxReplicas: number,
  metrics: [MetricSpec],
}

pub HorizontalPodAutoscaler = Object {
  apiVersion: `autoscaling/v2`,
  kind: `HorizontalPodAutoscaler`,
  metadata: Metadata,
  spec: HorizontalPodAutoscalerSpec,
}
```

```rank title="examples/kubernetes-app/main.rank"
/// Emits a small Kubernetes application bundle from one typed service
/// definition. Shows shared types, derived manifests, and Emit::manifest.

use std::Emit
use std::Path
use root::types::{
  AppSpec,
  ConfigMap,
  Deployment,
  HorizontalPodAutoscaler,
  Ingress,
  LabelMap,
  Metadata,
  Service,
}

app: AppSpec = {
  name: `payments-api`,
  namespace: `platform`,
  image: `ghcr.io/acme/payments-api:1.4.0`,
  containerPort: 8080,
  servicePort: 80,
  host: `payments.example.internal`,
  minReplicas: 2,
  maxReplicas: 6,
  cpuTargetUtilization: 70,
  env: {
    APP_ENV: `staging`,
    LOG_LEVEL: `info`,
    FEATURE_LEDGER_EXPORT: `enabled`,
    JVM_OPTS: `-Xms256m -Xmx512m`,
  },
}

labels: LabelMap = {
  `app.kubernetes.io/name`: app.name,
  `app.kubernetes.io/component`: `api`,
  `app.kubernetes.io/part-of`: `payments-platform`,
  `app.kubernetes.io/managed-by`: `rank`,
}

config_map_name = `${app.name}-config`
service_name = app.name
ingress_name = `${app.name}-ingress`
hpa_name = `${app.name}-hpa`

metadata_for = |name: string| -> Metadata {
  return {
    name: name,
    namespace: app.namespace,
    labels: labels,
  }
}

config_map: ConfigMap = {
  apiVersion: `v1`,
  kind: `ConfigMap`,
  metadata: metadata_for(config_map_name),
  data: {
    APP_ENV: app.env.APP_ENV,
    LOG_LEVEL: app.env.LOG_LEVEL,
    FEATURE_LEDGER_EXPORT: app.env.FEATURE_LEDGER_EXPORT,
    JVM_OPTS: app.env.JVM_OPTS,
  },
}

deployment: Deployment = {
  apiVersion: `apps/v1`,
  kind: `Deployment`,
  metadata: metadata_for(app.name),
  spec: {
    replicas: app.minReplicas,
    selector: {
      matchLabels: labels,
    },
    template: {
      metadata: {
        labels: labels,
      },
      spec: {
        containers: [
          {
            name: app.name,
            image: app.image,
            ports: [
              {
                containerPort: app.containerPort,
              },
            ],
            envFrom: [
              {
                configMapRef: {
                  name: config_map_name,
                },
              },
            ],
          },
        ],
      },
    },
  },
}

service: Service = {
  apiVersion: `v1`,
  kind: `Service`,
  metadata: metadata_for(service_name),
  spec: {
    type: `ClusterIP`,
    selector: labels,
    ports: [
      {
        port: app.servicePort,
        targetPort: app.containerPort,
      },
    ],
  },
}

ingress: Ingress = {
  apiVersion: `networking.k8s.io/v1`,
  kind: `Ingress`,
  metadata: metadata_for(ingress_name),
  spec: {
    ingressClassName: `nginx`,
    rules: [
      {
        host: app.host,
        http: {
          paths: [
            {
              path: `/`,
              pathType: `Prefix`,
              backend: {
                service: {
                  name: service_name,
                  port: {
                    number: app.servicePort,
                  },
                },
              },
            },
          ],
        },
      },
    ],
  },
}

hpa: HorizontalPodAutoscaler = {
  apiVersion: `autoscaling/v2`,
  kind: `HorizontalPodAutoscaler`,
  metadata: metadata_for(hpa_name),
  spec: {
    scaleTargetRef: {
      apiVersion: `apps/v1`,
      kind: `Deployment`,
      name: app.name,
    },
    minReplicas: app.minReplicas,
    maxReplicas: app.maxReplicas,
    metrics: [
      {
        type: `Resource`,
        resource: {
          name: `cpu`,
          target: {
            type: `Utilization`,
            averageUtilization: app.cpuTargetUtilization,
          },
        },
      },
    ],
  },
}

pub main = || Emit::manifest({
  entries: [
    {
      path: Path::join([`k8s`, `configmap.yaml`]),
      format: `yaml`,
      value: config_map,
    },
    {
      path: Path::join([`k8s`, `deployment.yaml`]),
      format: `yaml`,
      value: deployment,
    },
    {
      path: Path::join([`k8s`, `service.yaml`]),
      format: `yaml`,
      value: service,
    },
    {
      path: Path::join([`k8s`, `ingress.yaml`]),
      format: `yaml`,
      value: ingress,
    },
    {
      path: Path::join([`k8s`, `hpa.yaml`]),
      format: `yaml`,
      value: hpa,
    },
  ]
})
```

## Output

Running the example with `--file-root` writes these files:

- `k8s/configmap.yaml`
- `k8s/deployment.yaml`
- `k8s/service.yaml`
- `k8s/ingress.yaml`
- `k8s/hpa.yaml`

```yaml
# k8s/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: payments-api
  namespace: platform
  labels:
    app.kubernetes.io/name: payments-api
    app.kubernetes.io/component: api
    app.kubernetes.io/part-of: payments-platform
    app.kubernetes.io/managed-by: rank
spec:
  replicas: 2
  selector:
    matchLabels:
      app.kubernetes.io/name: payments-api
      app.kubernetes.io/component: api
      app.kubernetes.io/part-of: payments-platform
      app.kubernetes.io/managed-by: rank
  template:
    metadata:
      labels:
        app.kubernetes.io/name: payments-api
        app.kubernetes.io/component: api
        app.kubernetes.io/part-of: payments-platform
        app.kubernetes.io/managed-by: rank
    spec:
      containers:
        - name: payments-api
          image: ghcr.io/acme/payments-api:1.4.0
          ports:
            - containerPort: 8080
          envFrom:
            - configMapRef:
                name: payments-api-config
```

```yaml
# k8s/hpa.yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: payments-api-hpa
  namespace: platform
  labels:
    app.kubernetes.io/name: payments-api
    app.kubernetes.io/component: api
    app.kubernetes.io/part-of: payments-platform
    app.kubernetes.io/managed-by: rank
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: payments-api
  minReplicas: 2
  maxReplicas: 6
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
```

## Key concepts

- **Single typed app spec** drives every Kubernetes artifact instead of hand-editing multiple YAML files.
- **Shared metadata helper** keeps labels and namespace consistent across Deployment, Service, Ingress, ConfigMap, and HPA.
- **`Emit::manifest(...)`** emits multiple named files from one Rank program.
- **ConfigMap-backed container configuration** keeps runtime settings alongside the workload definition.
- **Autoscaling policy as data** makes min/max replicas and CPU targets part of the checked program.

## Run it

```sh
rank examples/kubernetes-app --file-root out/kubernetes-app
```

---

## LocalStack Bootstrap


Create empty LocalStack-backed AWS resources first, then use one Rank mutation plan to seed DynamoDB and S3 together.

## Source

```rank title="examples/localstack-bootstrap/types.rank"
use aws::DynamoDB::{ Table }

pub SeedRow = Object {
  dataset: string,
  id: string,
  service: string,
  owner: string,
  enabled: bool,
}

pub SeedsTable = Table<SeedRow, `dataset`, `id`>

pub BootstrapBundle = Object {
  generatedBy: string,
  generatedAt: string,
  services: [Object {
    service: string,
    owner: string,
    enabled: bool,
  }],
}
```

```rank title="examples/localstack-bootstrap/main.rank"
/// Seeds LocalStack-backed DynamoDB and S3 resources in one mutation plan.
/// Shows Mutation::plan, Mutation::commit, and provider mutation effects.

use aws::{ DynamoDB, S3 }
use std::Env
use std::Mutation
use root::types::{ BootstrapBundle, SeedRow, SeedsTable }

SysEnv = Object {
  DYNAMODB_ENDPOINT?: string,
  S3_ENDPOINT?: string,
  ...: string,
}

{ DYNAMODB_ENDPOINT, S3_ENDPOINT } = Env<SysEnv> {}

dynamodb_endpoint = DYNAMODB_ENDPOINT ?? `http://127.0.0.1:4566`
s3_endpoint = S3_ENDPOINT ?? `http://127.0.0.1:4566`

table_name = `BootstrapSeeds`
bucket_name = `rank-bootstrap-seeds`
bundle_key = `bootstrap/services.json`

dynamo_client: aws::DynamoDB::ClientConfig = DynamoDB::createClient({
  region: `us-east-1`,
  endpoint: dynamodb_endpoint,
  credentials: {
    accessKeyId: `test`,
    secretAccessKey: `test`,
  },
})

s3_client: aws::S3::ClientConfig = S3::createClient({
  region: `us-east-1`,
  endpoint: s3_endpoint,
  credentials: {
    accessKeyId: `test`,
    secretAccessKey: `test`,
  },
})

put_web_seed_row: Mutation::Effect<SeedRow> = aws::DynamoDB::Put<SeedsTable> {
  client: dynamo_client,
  tableName: table_name,
}

put_api_seed_row: Mutation::Effect<SeedRow> = aws::DynamoDB::Put<SeedsTable> {
  client: dynamo_client,
  tableName: table_name,
}

put_bundle_seed: Mutation::Effect<BootstrapBundle> = aws::S3::Put<BootstrapBundle> {
  client: s3_client,
  bucket: bucket_name,
  key: bundle_key,
}

web_seed: SeedRow = {
  dataset: `services`,
  id: `web`,
  service: `web`,
  owner: `web-platform`,
  enabled: true,
}

api_seed: SeedRow = {
  dataset: `services`,
  id: `api`,
  service: `api`,
  owner: `payments`,
  enabled: true,
}

bundle_seed: BootstrapBundle = {
  generatedBy: `localstack-bootstrap`,
  generatedAt: `2026-05-13`,
  services: [
    {
      service: web_seed.service,
      owner: web_seed.owner,
      enabled: web_seed.enabled,
    },
    {
      service: api_seed.service,
      owner: api_seed.owner,
      enabled: api_seed.enabled,
    },
  ],
}

pub main = || Mutation::commit(
  Mutation::plan({
    webSeed: put_web_seed_row(web_seed),
    apiSeed: put_api_seed_row(api_seed),
    bundleSeed: put_bundle_seed(bundle_seed),
  }),
  |report| {
    commitStatus: report.status,
    targets: {
      tableName: table_name,
      bucket: bucket_name,
      key: bundle_key,
    },
    operations: report.operations,
  },
)
```

```toml title="examples/localstack-bootstrap/rank.toml"
manifestVersion = 1

[package]
name = "localstack-bootstrap-example"
version = "0.1.0"
source = "."

[providers]
aws = { path = "../../packages/plugins/aws" }

[security]
allow-provider-capabilities = ["network"]
allow-provider-mutation-exports = ["aws::DynamoDB::Put", "aws::S3::Put"]
allow-env = ["DYNAMODB_ENDPOINT", "S3_ENDPOINT"]
```

## Output

```yaml
commitStatus: succeeded
targets:
  tableName: BootstrapSeeds
  bucket: rank-bootstrap-seeds
  key: bootstrap/services.json
operations:
  webSeed:
    status: succeeded
  apiSeed:
    status: succeeded
  bundleSeed:
    status: succeeded
```

## Run it

Start LocalStack from the example directory:

```sh
cd examples/localstack-bootstrap
docker compose up
```

Then run the Rank program from the workspace root:

```sh
npm run rank -- examples/localstack-bootstrap
```

If you changed the LocalStack host port, pass matching endpoints:

```sh
DYNAMODB_ENDPOINT=http://127.0.0.1:4567 S3_ENDPOINT=http://127.0.0.1:4567 npm run rank -- examples/localstack-bootstrap
```

## Key concepts

- **`Mutation::plan(...)`** groups multiple provider writes into one commit boundary.
- **Direct effect bindings** keep the mutation graph explicit: each plan field calls a named local `Mutation::Effect` binding.
- **Mixed AWS mutations** seed DynamoDB rows and an S3 object in the same commit.
- **LocalStack-backed workflow** keeps the example runnable without touching real AWS resources.

---

## Multi-env App


Read `RANK_ENV` from the environment and produce an environment-specific configuration by patching a shared base config.

## Source

```rank title="examples/multi-env-app/base.rank"
/// Shared base configuration for all environments.

pub AppBase = Object {
  name: string,
  port: number,
  replicas: number,
  logLevel: string,
  db: Object {
    host: string,
    port: number,
    name: string,
    poolSize: number,
  },
}

pub base: AppBase = {
  name: `my-app`,
  port: 8080,
  replicas: 1,
  logLevel: `info`,
  db: {
    host: `localhost`,
    port: 5432,
    name: `app`,
    poolSize: 5,
  },
}
```

```rank title="examples/multi-env-app/main.rank"
/// Reads RANK_ENV from the environment and produces an environment-specific
/// config by patching the shared base with per-environment overrides.
/// Shows Env inputs, match on a union type, and the `with` override pattern.

use std::Env
use root::base::{ base, AppBase }

SysEnv = Object {
  RANK_ENV?: `dev` | `staging` | `prod` | null,
  ...: string,
}

{ RANK_ENV } = Env<SysEnv> {}

config: AppBase = match RANK_ENV ?? `dev` {
  `dev` => base with {
    logLevel: `debug`,
    db: base.db with { poolSize: 2 },
  },
  `staging` => base with {
    replicas: 2,
    db: base.db with {
      host: `db.staging.internal`,
      poolSize: 10,
    },
  },
  `prod` => base with {
    replicas: 5,
    logLevel: `warn`,
    db: base.db with {
      host: `db.prod.internal`,
      poolSize: 25,
    },
  },
}

pub main = || config
```

## Output

```json
// RANK_ENV=prod
{
  "name": "my-app",
  "port": 8080,
  "replicas": 5,
  "logLevel": "warn",
  "db": {
    "host": "db.prod.internal",
    "port": 5432,
    "name": "app",
    "poolSize": 25
  }
}
```

## Key concepts

- **`std::Env`** — reads environment variables into a typed schema. `RANK_ENV` is constrained at the boundary to `` `dev` | `staging` | `prod` | null `` instead of being normalized later from an arbitrary `string`.
- **Destructuring env inputs** — `{ RANK_ENV } = Env<SysEnv> {}` pulls the field you care about into a local binding while keeping the schema on the `Env` call.
- **`match` on a literal union** — `match RANK_ENV ?? `dev`` branches over the closed set of allowed environments with an explicit default when the variable is unset.
- **Nested `with`** — `base with { db: base.db with { poolSize: 25 } }` patches deeply without touching unrelated fields.
- **Multi-file modules** — `base.rank` exports the shared type and value; this example imports them via the canonical absolute form `root::base`. In a normal project source tree, a nearby sibling import can also use `super::base` when that reads better.

## Run it

```sh
RANK_ENV=prod rank examples/multi-env-app
RANK_ENV=staging rank examples/multi-env-app
rank examples/multi-env-app   # defaults to dev
```

---

## Pipes and Collections


The pipe operator `|>` with `map`, `filter`, `reduce`, `groupBy`, `sortBy`, and `keyBy`.

## Source

```rank title="examples/pipes-and-collections/main.rank"
/// Demonstrates the pipe operator and stdlib collection functions:
/// map, filter, reduce, groupBy, sortBy, and keyBy.

use std::collections::{ map, filter, reduce, groupBy, sortBy, keyBy }
use std::object::{ mapValues }

Service = Object {
  name: string,
  team: string,
  port: number,
  replicas: number,
}

services: [Service] = [
  { name: `api`, team: `backend`, port: 8080, replicas: 3 },
  { name: `worker`, team: `backend`, port: 9090, replicas: 2 },
  { name: `web`, team: `frontend`, port: 3000, replicas: 4 },
  { name: `admin`, team: `frontend`, port: 7070, replicas: 1 },
]

active_services = services |> filter(|svc: Service| svc.replicas > 1)

named_services = services |> map(|svc: Service| `${svc.name}:${svc.team}`)

total_replicas = services |> reduce(0, |acc: number, svc: Service| acc + svc.replicas)

by_team = services |> groupBy(|svc: Service| svc.team)

by_name = services |> keyBy(|svc: Service| svc.name)

sorted_by_port = services |> sortBy(|svc: Service| svc.port)

replica_map = services
  |> keyBy(|svc: Service| svc.name)
  |> mapValues(|svc: Service, name: string| svc.replicas)

pub main = || {
  active_services,
  named_services,
  total_replicas,
  by_team,
  by_name,
  sorted_by_port,
  replica_map,
}
```

## Output

```json
{
  "active_services": [
    { "name": "api", "team": "backend", "port": 8080, "replicas": 3 },
    { "name": "worker", "team": "backend", "port": 9090, "replicas": 2 },
    { "name": "web", "team": "frontend", "port": 3000, "replicas": 4 }
  ],
  "named_services": ["api:backend", "worker:backend", "web:frontend", "admin:frontend"],
  "total_replicas": 10,
  "by_team": {
    "backend": [
      { "name": "api", "team": "backend", "port": 8080, "replicas": 3 },
      { "name": "worker", "team": "backend", "port": 9090, "replicas": 2 }
    ],
    "frontend": [
      { "name": "web", "team": "frontend", "port": 3000, "replicas": 4 },
      { "name": "admin", "team": "frontend", "port": 7070, "replicas": 1 }
    ]
  },
  "sorted_by_port": [
    { "name": "web", "team": "frontend", "port": 3000, "replicas": 4 },
    { "name": "admin", "team": "frontend", "port": 7070, "replicas": 1 },
    { "name": "api", "team": "backend", "port": 8080, "replicas": 3 },
    { "name": "worker", "team": "backend", "port": 9090, "replicas": 2 }
  ],
  "replica_map": { "api": 3, "worker": 2, "web": 4, "admin": 1 }
}
```

## Key concepts

- **Pipe `|>`** — `services |> filter(...)` passes `services` as the first argument to `filter`. Chains read left-to-right.
- **`groupBy`** — partitions a list into an object whose keys are the return values of the callback.
- **`keyBy`** — like `groupBy` but asserts each key appears exactly once, returning an object of single values.
- **`mapValues`** — transforms only the values of an object, leaving keys intact.
- **`reduce`** — folds a list to a single value. The accumulator type is inferred from the `initial` argument.

## Run it

```sh
rank examples/pipes-and-collections
```

---

## Provider Comparison


Normalize environment variables, a local file, an HTTP response, and a seeded S3 object into one shared output schema.

## Source

```yaml title="examples/provider-comparison/input.yaml"
id: file-001
label: File Snapshot
owner: docs-team
```

```rank title="examples/provider-comparison/main.rank"
/// Normalizes environment, file, HTTP, and S3 inputs into one schema.
/// Shows multiple input surfaces converging on one output bundle.

use aws::{ S3 }
use std::Emit
use std::Env
use std::File
use std::HTTP
use std::Path
use std::collections::{ length, map }

SourceRecord = Object {
  id: string,
  label: string,
  owner: string,
}

NormalizedRecord = Object {
  source: `env` | `file` | `http` | `s3`,
  id: string,
  label: string,
  owner: string,
}

ArticleAuthor = Object {
  id: string,
  name: string,
  avatar: string,
  email: string,
}

Article = Object {
  slug: string,
  title: string,
  subtitle: string,
  image: string,
  author: ArticleAuthor,
  dateCreated: string,
  content: string,
}

SysEnv = Object {
  PRODUCT_ID?: string,
  PRODUCT_LABEL?: string,
  PRODUCT_OWNER?: string,
  S3_ENDPOINT?: string,
  ...: string,
}

{ PRODUCT_ID, PRODUCT_LABEL, PRODUCT_OWNER, S3_ENDPOINT } = Env<SysEnv> {}

env_record: NormalizedRecord = {
  source: `env`,
  id: PRODUCT_ID ?? `env-001`,
  label: PRODUCT_LABEL ?? `Environment Snapshot`,
  owner: PRODUCT_OWNER ?? `platform-runtime`,
}

file_result = File::Read<SourceRecord> {
  path: Path::join([`input.yaml`]),
  format: `yaml`,
}

file_record: NormalizedRecord = {
  source: `file`,
  id: file_result.body.id,
  label: file_result.body.label,
  owner: file_result.body.owner,
}

http_result = HTTP::Fetch<Article> {
  url: `https://lorem-api.com/api/article/rank-http-fetch`,
  method: `GET`,
  headers: {
    Accept: `application/json`,
  },
  cacheKey: `provider-comparison-rank-http-fetch-v1`,
}

http_record: NormalizedRecord = {
  source: `http`,
  id: http_result.body.slug,
  label: http_result.body.title,
  owner: http_result.body.author.email,
}

s3_endpoint = S3_ENDPOINT ?? `http://127.0.0.1:4566`

s3_client: aws::S3::ClientConfig = S3::createClient({
  region: `us-east-1`,
  endpoint: s3_endpoint,
  credentials: {
    accessKeyId: `test`,
    secretAccessKey: `test`,
  },
})

s3_result: aws::S3::ObjectResult<SourceRecord> = aws::S3::Object<SourceRecord> {
  client: s3_client,
  bucket: `rank-provider-comparison`,
  key: `profiles/source.json`,
}

s3_record: NormalizedRecord = {
  source: `s3`,
  id: s3_result.object.id,
  label: s3_result.object.label,
  owner: s3_result.object.owner,
}

records: [NormalizedRecord] = [env_record, file_record, http_record, s3_record]

summary = {
  totalSources: length(records),
  sources: records |> map(|record: NormalizedRecord| record.source),
}

pub main = || Emit::manifest({
  entries: [
    {
      path: Path::join([`comparison`, `normalized.json`]),
      format: `json`,
      value: records,
    },
    {
      path: Path::join([`comparison`, `summary.yaml`]),
      format: `yaml`,
      value: summary,
    },
  ]
})
```

## Output

```yaml
totalSources: 4
sources:
  - env
  - file
  - http
  - s3
```

## Run it

Start LocalStack from the example directory:

```sh
cd examples/provider-comparison
docker compose up
```

Then run the Rank program from the workspace root:

```sh
npm run rank -- examples/provider-comparison --file-root out/provider-comparison
```

Optionally override the environment-backed record:

```sh
PRODUCT_LABEL="Env Override" npm run rank -- examples/provider-comparison --file-root out/provider-comparison
```

## Key concepts

- `Env`, `File::Read`, `HTTP::Fetch`, and `aws::S3::Object<T>` can all normalize into one shared schema.
- The S3 input stays local and reproducible by seeding LocalStack in `docker-compose.yml`.
- A single emitted bundle makes cross-provider comparisons straightforward to inspect.

---

## S3 Logs


Read mock nginx access logs from S3 through the AWS provider, parse each line with `parse` string patterns, and expose the result through `rank serve`.

## Source

```rank title="examples/s3-logs/main.rank"
use aws::{ S3 }
use std::Env
use std::HTTP
use std::Runtime
use std::collections::{ count, filter, flatMap, length, map }
use std::string::{ isBlank, startsWith, split, trim }

LogDay = `2026-05-11` | `2026-05-12`
StatusClass = `2xx` | `3xx` | `4xx` | `5xx` | `other`

AccessLogFile = Object {
  format: `nginx-access`,
  server: string,
  day: LogDay,
  raw: string,
}

AccessLogEntry = Object {
  raw: string,
  clientIp: string,
  timestamp: string,
  method: string,
  target: string,
  protocol: string,
  status: string,
  statusClass: StatusClass,
  bytesSent: string,
  referrer: string,
  userAgent: string,
}

SysEnv = Object {
  S3_ENDPOINT?: string,
  ...: string,
}

HealthRoute = HTTP::Route {
  method: `GET`,
  path: `/health`
}

LogsRoute = HTTP::Route {
  method: `GET`,
  path: `/logs`,
  query: Object {
    day?: LogDay,
  }
}

Routes = HealthRoute | LogsRoute

log_bucket = `rank-example-logs`
default_log_day: LogDay = `2026-05-12`
available_log_days: [LogDay] = [`2026-05-11`, `2026-05-12`]

{ S3_ENDPOINT } = Env<SysEnv> {}
s3_endpoint = S3_ENDPOINT ?? `http://127.0.0.1:4566`

s3Client: aws::S3::ClientConfig = S3::createClient({
  region: `us-east-1`,
  endpoint: s3_endpoint,
  credentials: {
    accessKeyId: `test`,
    secretAccessKey: `test`,
  },
})

status_class_for = |status: string| -> StatusClass {
  return startsWith(status, `2`) ? `2xx`
    : startsWith(status, `3`) ? `3xx`
    : startsWith(status, `4`) ? `4xx`
    : startsWith(status, `5`) ? `5xx`
    : `other`
}

log_key_for = |day: LogDay| -> string {
  return match day {
    `2026-05-11` => `nginx/2026-05-11/access.json`,
    `2026-05-12` => `nginx/2026-05-12/access.json`,
  }
}

parse_access_entries = |line: string| -> [AccessLogEntry] {
  return match line {
    parse`{clientIp:string} - {_remoteUser:string} [{timestamp:string}] "{method:string} {target:string} HTTP/{protocol:string}" {status:string} {bytesSent:string} "{referrer:string}" "{userAgent:string}"` => [{
      raw: line,
      clientIp,
      timestamp,
      method,
      target,
      protocol,
      status,
      statusClass: status_class_for(status),
      bytesSent,
      referrer,
      userAgent,
    }],
    _ => [],
  }
}

list_logs = |day: LogDay| -> HTTP::Response {
  key = log_key_for(day)

  fetched: aws::S3::ObjectResult<AccessLogFile> = aws::S3::Object<AccessLogFile> {
    client: s3Client,
    bucket: log_bucket,
    key: key,
  }

  { object, metadata } = fetched

  non_blank_lines = object.raw
    |> split(`\n`)
    |> map(|line: string| trim(line))
    |> filter(|line: string| !isBlank(line))

  entries = non_blank_lines
    |> flatMap(|line: string| parse_access_entries(line))

  return {
    status: 200,
    body: {
      availableDays: available_log_days,
      source: {
        bucket: log_bucket,
        key: key,
        server: object.server,
        day: object.day,
        requestId: metadata.requestId,
      },
      summary: {
        totalLines: length(non_blank_lines),
        parsedLines: length(entries),
        droppedLines: length(non_blank_lines) - length(entries),
        okResponses: count(entries, |entry: AccessLogEntry| entry.statusClass == `2xx`),
        redirects: count(entries, |entry: AccessLogEntry| entry.statusClass == `3xx`),
        clientErrors: count(entries, |entry: AccessLogEntry| entry.statusClass == `4xx`),
        serverErrors: count(entries, |entry: AccessLogEntry| entry.statusClass == `5xx`),
      },
      entries: entries,
    }
  }
}

pub config = {
  defaultResponseFormat: `json`
}

pub main = |req: Runtime::ExecutionContext<Routes>| -> HTTP::Response {
  return match req {
    HealthRoute => {
      status: 200,
      body: {
        ok: true,
        service: `s3-logs-example`,
      },
    },
    LogsRoute => list_logs(req.query.day ?? default_log_day),
  }
}
```

```toml title="examples/s3-logs/rank.toml"
manifestVersion = 1

[package]
name = "s3-logs-example"
version = "0.1.0"
source = "."

[providers]
aws = { path = "../../packages/plugins/aws" }

[security]
allow-provider-capabilities = ["network"]
allow-env = ["S3_ENDPOINT"]
```

## Output

```json
{
  "availableDays": ["2026-05-11", "2026-05-12"],
  "source": {
    "bucket": "rank-example-logs",
    "key": "nginx/2026-05-12/access.json",
    "server": "edge-2",
    "day": "2026-05-12"
  },
  "summary": {
    "totalLines": 5,
    "parsedLines": 5,
    "droppedLines": 0,
    "okResponses": 1,
    "redirects": 0,
    "clientErrors": 2,
    "serverErrors": 2
  }
}
```

## Key concepts

- **`aws::S3::Object<T>`** — reads the seeded object from S3 and validates the wrapper shape before any line parsing runs.
- **`parse` string patterns** — the log parser uses a single structured-text `match` arm instead of separate regex capture indexing.
- **Pipe + `flatMap`** — the raw text is split, trimmed, filtered, and parsed through one left-to-right collection flow.
- **`Runtime::ExecutionContext<Routes>`** — `GET /health` and `GET /logs` share one route union with typed query narrowing for `day`.
- **Current S3 surface** — the current AWS provider reads S3 objects as JSON only, so the seeded raw nginx text lives inside the `raw` field of a JSON object.

## Run it

Start LocalStack from `examples/s3-logs`:

```sh
docker compose up
```

If another LocalStack setup is already using port `4566`, choose a different host port:

```sh
LOCALSTACK_PORT=4567 docker compose up
```

Then start the Rank server from the repository root:

```sh
npm start -- serve examples/s3-logs --dev
```

If you changed the LocalStack port, pass the matching endpoint to the Rank server:

```sh
S3_ENDPOINT=http://127.0.0.1:4567 npm start -- serve examples/s3-logs --dev
```

Try it:

```sh
curl http://127.0.0.1:3000/health
curl http://127.0.0.1:3000/logs
curl 'http://127.0.0.1:3000/logs?day=2026-05-11'
```

---

## Secrets-Backed Config


Resolve an application config from a shared base object, the selected `RANK_ENV`, and a JSON secret fetched from AWS Secrets Manager.

This example is backed by LocalStack so the provider call is runnable in the repository without a real AWS account.

## Source

```rank title="examples/secrets-backed-config/types.rank"
pub Environment = `dev` | `staging` | `prod`

pub LogLevel = `debug` | `info` | `warn`

pub BaseConfig = Object {
  service: Object {
    name: string,
    baseUrl: string,
    logLevel: LogLevel,
  },
  database: Object {
    host: string,
    port: number,
    name: string,
    user: string,
  },
  auth: Object {
    issuer: string,
  },
  integrations: Object {
    billingApiBaseUrl: string,
  },
}

pub RuntimeSecrets = Object {
  dbPassword: string,
  jwtSigningSecret: string,
  stripeApiKey: string,
}

pub ResolvedConfig = Object {
  service: Object {
    name: string,
    env: Environment,
    baseUrl: string,
    logLevel: LogLevel,
  },
  database: Object {
    host: string,
    port: number,
    name: string,
    user: string,
    password: string,
  },
  auth: Object {
    issuer: string,
    jwtSigningSecret: string,
  },
  integrations: Object {
    billingApiBaseUrl: string,
    stripeApiKey: string,
  },
  source: Object {
    secretId: string,
  },
}
```

```rank title="examples/secrets-backed-config/main.rank"
/// Resolves a deployable app config from a shared base, the selected
/// environment, and a JSON secret fetched from AWS Secrets Manager.

use aws::{ SecretsManager }
use std::Env
use root::types::{ BaseConfig, Environment, LogLevel, ResolvedConfig, RuntimeSecrets }

SysEnv = Object {
  RANK_ENV?: Environment,
  SECRETS_ENDPOINT?: string,
  ...: string,
}

{ RANK_ENV, SECRETS_ENDPOINT } = Env<SysEnv> {}

selected_env: Environment = RANK_ENV ?? `staging`
secrets_endpoint = SECRETS_ENDPOINT ?? `http://127.0.0.1:4566`

base: BaseConfig = {
  service: {
    name: `payments-api`,
    baseUrl: `https://payments.internal`,
    logLevel: `info`,
  },
  database: {
    host: `db.internal`,
    port: 5432,
    name: `payments`,
    user: `payments_app`,
  },
  auth: {
    issuer: `https://auth.internal/issuer`,
  },
  integrations: {
    billingApiBaseUrl: `https://billing.internal/api`,
  },
}

log_level_for = |env: Environment| -> LogLevel {
  return match env {
    `dev` => `debug`,
    `staging` => `info`,
    `prod` => `warn`,
  }
}

secret_id_for = |env: Environment| -> string {
  return match env {
    `dev` => `rank/examples/payments-api/dev`,
    `staging` => `rank/examples/payments-api/staging`,
    `prod` => `rank/examples/payments-api/prod`,
  }
}

env_config: BaseConfig = match selected_env {
  `dev` => base with {
    service: base.service with {
      baseUrl: `https://payments.dev.internal`,
      logLevel: log_level_for(selected_env),
    },
    database: base.database with {
      host: `dev-db.internal`,
    },
    integrations: base.integrations with {
      billingApiBaseUrl: `https://billing.dev.internal/api`,
    },
  },
  `staging` => base with {
    service: base.service with {
      baseUrl: `https://payments.staging.internal`,
      logLevel: log_level_for(selected_env),
    },
    database: base.database with {
      host: `staging-db.internal`,
    },
    integrations: base.integrations with {
      billingApiBaseUrl: `https://billing.staging.internal/api`,
    },
  },
  `prod` => base with {
    service: base.service with {
      baseUrl: `https://payments.example.com`,
      logLevel: log_level_for(selected_env),
    },
    database: base.database with {
      host: `payments-db.internal`,
    },
    integrations: base.integrations with {
      billingApiBaseUrl: `https://billing.example.com/api`,
    },
  },
}

secrets_client: aws::SecretsManager::ClientConfig = SecretsManager::createClient({
  region: `us-east-1`,
  endpoint: secrets_endpoint,
  credentials: {
    accessKeyId: `test`,
    secretAccessKey: `test`,
  },
})

secret_id = secret_id_for(selected_env)

secret_result: aws::SecretsManager::SecretResult<RuntimeSecrets> = aws::SecretsManager::Secret<RuntimeSecrets> {
  client: secrets_client,
  secretId: secret_id,
  format: `json`,
}

pub main = || -> ResolvedConfig {
  return {
    service: env_config.service with {
      env: selected_env,
    },
    database: env_config.database with {
      password: secret_result.secret.dbPassword,
    },
    auth: env_config.auth with {
      jwtSigningSecret: secret_result.secret.jwtSigningSecret,
    },
    integrations: env_config.integrations with {
      stripeApiKey: secret_result.secret.stripeApiKey,
    },
    source: {
      secretId: secret_id,
    },
  }
}
```

```toml title="examples/secrets-backed-config/rank.toml"
manifestVersion = 1

[package]
name = "secrets-backed-config-example"
version = "0.1.0"
source = "."

[providers]
aws = { path = "../../packages/plugins/aws" }

[security]
allow-provider-capabilities = ["network"]
allow-env = ["RANK_ENV", "SECRETS_ENDPOINT"]
```

## Output

Default output with `RANK_ENV` unset:

```yaml
service:
  name: payments-api
  baseUrl: https://payments.staging.internal
  logLevel: info
  env: staging
database:
  host: staging-db.internal
  port: 5432
  name: payments
  user: payments_app
  password: staging-db-password
auth:
  issuer: https://auth.internal/issuer
  jwtSigningSecret: staging-jwt-signing-secret
integrations:
  billingApiBaseUrl: https://billing.staging.internal/api
  stripeApiKey: sk_test_staging_456
source:
  secretId: rank/examples/payments-api/staging
```

## Run it

Start LocalStack from the example directory:

```sh
cd examples/secrets-backed-config
docker compose up
```

Then run the Rank program from the workspace root:

```sh
npm run rank -- examples/secrets-backed-config
```

Switch environments with `RANK_ENV`:

```sh
RANK_ENV=prod npm run rank -- examples/secrets-backed-config
```

If you changed the LocalStack host port, pass the matching endpoint:

```sh
RANK_ENV=prod SECRETS_ENDPOINT=http://127.0.0.1:4567 npm run rank -- examples/secrets-backed-config
```

## Key concepts

- **`aws::SecretsManager::Secret<T>`** fetches a typed secret payload and decodes JSON directly into a checked Rank object.
- **Base + environment patching** uses `with` to keep the stable config shape separate from environment-specific overrides.
- **`std::Env` selection** turns `RANK_ENV` into typed branching instead of ad hoc string checks.
- **LocalStack-backed provider example** keeps the example runnable in-repo while still exercising the real provider surface.

---

## Serve — Docker


Package a Rank HTTP app into a container image using `rank serve`.

## Source

```rank title="examples/serve-docker/main.rank"
use std::HTTP

HealthRoute = HTTP::Route {
  method: `GET`,
  path: `/health`
}

Routes = HealthRoute

pub config = {
  defaultResponseFormat: `json`
}

pub main = || -> HTTP::Response {
  return {
    status: 200,
    body: {
      ok: true,
      service: `serve-docker-example`
    }
  }
}
```

```toml title="examples/serve-docker/rank.toml"
manifestVersion = 1

[package]
name = "serve-docker-example"
version = "0.1.0"
source = "."
```

```dockerfile title="examples/serve-docker/Dockerfile"
FROM node:22-slim

WORKDIR /app

RUN npm install -g @rank-lang/cli

COPY rank.toml main.rank ./

RUN rank sync .

EXPOSE 3000

CMD ["rank", "serve", ".", "--host", "0.0.0.0", "--port", "3000"]
```

## Build and run

```sh
docker build -t rank-serve-example .
docker run --rm -p 3000:3000 rank-serve-example
```

```sh
curl http://127.0.0.1:3000/health
```

```json
{
  "ok": true,
  "service": "serve-docker-example"
}
```

For local parity without Docker:

```sh
rank serve . --host 127.0.0.1 --port 3000
```

## Key concepts

- **`rank sync .`** — runs during the Docker build to cache all registry dependencies. The container starts without making outbound package requests.
- **`--host 0.0.0.0`** — binds to all interfaces so traffic forwarded by Docker reaches the server. In local development use `127.0.0.1` (the default).
- **`pub config`** — sets `defaultResponseFormat: \`json\`` so all route responses are serialized as JSON without having to specify `format` on each one.
- **`/.well-known/rank/ready`** — built-in readiness endpoint managed by the server runtime, not part of the application route table. Use it for Docker health checks or load-balancer probes.

---

## Serve — Lambda Web Adapter


Deploy a Rank HTTP app to AWS Lambda using the [Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter) and a `provided.al2023` custom runtime — no container image required.

The adapter is attached as a Lambda Layer. It translates Lambda invocations into HTTP requests forwarded to `rank serve`, so the Rank app needs no Lambda-specific handler code.

## Source

```rank title="examples/serve-lambda/main.rank"
use std::HTTP
use std::Runtime

HealthRoute = HTTP::Route {
  method: `GET`,
  path: `/health`
}

Routes = HealthRoute

pub config = {
  defaultResponseFormat: `json`
}

pub main = |req: Runtime::ExecutionContext<Routes>| -> HTTP::Response {
  return {
    status: 200,
    body: {
      ok: true,
      service: `serve-lambda-web-adapter-example`
    }
  }
}
```

```sh title="examples/serve-lambda/bootstrap"
#!/bin/sh
export PATH="$LAMBDA_TASK_ROOT/bin:$LAMBDA_TASK_ROOT/node_modules/.bin:$PATH"
exec rank serve "$LAMBDA_TASK_ROOT" --host 0.0.0.0 --port "${PORT:-8080}"
```

```makefile title="examples/serve-lambda/Makefile"
.PHONY: build-RankApp

build-RankApp:
  dnf install -y nodejs npm 2>/dev/null || true
  npm install --prefix "$(ARTIFACTS_DIR)" @rank-lang/cli
  "$(ARTIFACTS_DIR)/node_modules/.bin/rank" sync .
  cp main.rank rank.toml "$(ARTIFACTS_DIR)/"
  cp bootstrap "$(ARTIFACTS_DIR)/"
  chmod +x "$(ARTIFACTS_DIR)/bootstrap"
  mkdir -p "$(ARTIFACTS_DIR)/bin"
  cp "$$(which node)" "$(ARTIFACTS_DIR)/bin/"
```

```yaml title="examples/serve-lambda/template.yaml"
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31

Globals:
  Function:
    Timeout: 30
    MemorySize: 512

Resources:
  RankApp:
    Type: AWS::Serverless::Function
    Properties:
      Runtime: provided.al2023
      Architectures:
        - x86_64
      Handler: bootstrap
      CodeUri: ./
      Layers:
        - !Sub arn:aws:lambda:${AWS::Region}:753240598075:layer:LambdaAdapterLayerX86:24
      Environment:
        Variables:
          PORT: '8080'
          READINESS_CHECK_PATH: /.well-known/rank/ready
      Events:
        Api:
          Type: HttpApi
          Properties:
            Path: /{proxy+}
            Method: ANY
        RootApi:
          Type: HttpApi
          Properties:
            Path: /
            Method: ANY
    Metadata:
      BuildMethod: makefile

Outputs:
  ApiUrl:
    Description: API Gateway endpoint
    Value: !Sub https://${ServerlessHttpApi}.execute-api.${AWS::Region}.amazonaws.com
```

## Build and deploy

Requires the [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html). Docker is used only for the SAM container build step, not the Lambda runtime.

There is no separate Rank compile step for this example. The Lambda source bundle is the example directory itself:

- `main.rank` is the Rank app source.
- `rank.toml` makes the directory runnable as `rank serve .`.
- `bootstrap` is the custom runtime entrypoint Lambda executes.
- `template.yaml` tells SAM to build the function with the local `Makefile` via `BuildMethod: makefile`.

Run the build from `examples/serve-lambda`:

```sh
cd examples/serve-lambda

# Build inside an Amazon Linux 2023 container so node matches the runtime
sam build --use-container

# First deploy (creates samconfig.toml)
sam deploy --guided
```

During `sam build`, SAM invokes the `build-RankApp` target from `Makefile` inside the AL2023 build container. The target name is `build-<LogicalId>`, so it matches the function resource name `RankApp` in `template.yaml`. SAM also sets `ARTIFACTS_DIR` to the staging directory that will become the Lambda bundle.

That target:
1. Installs Node.js via `dnf`
2. Installs `@rank-lang/cli` into the artifact directory
3. Runs `rank sync .` to pre-cache registry dependencies
4. Copies `main.rank`, `rank.toml`, and `bootstrap` into the Lambda artifact directory
5. Copies the node binary so it is available at `$LAMBDA_TASK_ROOT/bin/node` at runtime

After the build, the staged Lambda bundle is under `.aws-sam/build/RankApp/`. That directory is what SAM deploys to Lambda.

## Test it

```sh
curl https://<api-id>.execute-api.<region>.amazonaws.com/health
```

```json
{
  "ok": true,
  "service": "serve-lambda-web-adapter-example"
}
```

Local testing without Lambda:

```sh
rank serve . --host 127.0.0.1 --port 8080
```

Or with the SAM local emulator:

```sh
sam local start-api --port 8080
```

## Key concepts

- **`Runtime: provided.al2023`** — Lambda calls the `bootstrap` executable directly. No managed runtime is involved; rank serve is the only process.
- **Lambda Web Adapter layer** — the `LambdaAdapterLayerX86` layer adds an extension that translates Lambda invocations into HTTP requests and forwards them to the server on `PORT`.
- **`PORT=8080`** — the adapter forwards traffic to rank serve on this port.
- **`READINESS_CHECK_PATH=/.well-known/rank/ready`** — the adapter polls this built-in endpoint on startup and withholds traffic until rank serve is ready to accept connections.
- **`rank sync .` at build time** — caches registry dependencies so cold starts don't need outbound package requests.
- **No Lambda handler** — the Rank app is unaware it runs on Lambda. The same `rank serve` command works locally and behind the adapter.

---

## Service Catalog


Define a typed service catalog once and emit multiple downstream artifacts from it: service summary data, a CI matrix, public endpoint metadata, Docker Compose, and deployment metadata.

## Source

```rank title="examples/service-catalog/types.rank"
pub Team = `web-platform` | `payments` | `operations`

pub Tier = `frontend` | `api` | `worker`

pub Exposure = `public` | `internal`

pub ServiceDef = Object {
  name: string,
  image: string,
  owner: Team,
  tier: Tier,
  exposure: Exposure,
  buildCommand: string,
  testCommand: string,
  port?: number,
  dependsOn?: [string],
  healthPath?: string,
}

pub ComposeService = Object {
  image: string,
  ports?: [string],
  depends_on?: [string],
  environment: Object { ...: string },
}

pub Compose = Object {
  version: string,
  services: Object { ...: ComposeService },
}

pub ServiceSummary = Object {
  name: string,
  owner: Team,
  tier: Tier,
  exposure: Exposure,
}

pub MatrixEntry = Object {
  service: string,
  owner: Team,
  buildCommand: string,
  testCommand: string,
}

pub Matrix = Object {
  include: [MatrixEntry],
}

pub PublicEndpoint = Object {
  service: string,
  url: string,
  healthPath?: string,
}

pub DeploymentRecord = Object {
  service: string,
  owner: Team,
  image: string,
  tier: Tier,
  dependsOn: [string],
}

pub DeploymentBundle = Object {
  environment: string,
  services: [DeploymentRecord],
}
```

```rank title="examples/service-catalog/main.rank"
/// Emits multiple derived artifacts from one typed service catalog.
/// Shows shared source-of-truth data, collection transforms, and
/// Emit::manifest across JSON and YAML outputs.

use std::Emit
use std::Path
use std::collections::{ filter, map }
use root::types::{
  Compose,
  ComposeService,
  DeploymentBundle,
  DeploymentRecord,
  Matrix,
  MatrixEntry,
  PublicEndpoint,
  ServiceDef,
  ServiceSummary,
}

services: [ServiceDef] = [
  {
    name: `web`,
    image: `ghcr.io/acme/web:2.3.0`,
    owner: `web-platform`,
    tier: `frontend`,
    exposure: `public`,
    buildCommand: `npm run build -w web`,
    testCommand: `npm test -w web`,
    port: 3000,
    dependsOn: [`api`],
    healthPath: `/healthz`,
  },
  {
    name: `api`,
    image: `ghcr.io/acme/api:2.3.0`,
    owner: `payments`,
    tier: `api`,
    exposure: `internal`,
    buildCommand: `npm run build -w api`,
    testCommand: `npm test -w api`,
    port: 8080,
    dependsOn: [`redis`],
    healthPath: `/health`,
  },
  {
    name: `worker`,
    image: `ghcr.io/acme/worker:2.3.0`,
    owner: `operations`,
    tier: `worker`,
    exposure: `internal`,
    buildCommand: `npm run build -w worker`,
    testCommand: `npm test -w worker`,
    dependsOn: [`api`, `redis`],
  },
]

web = services[0]
api = services[1]
worker = services[2]

summary_for = |service: ServiceDef| -> ServiceSummary {
  return {
    name: service.name,
    owner: service.owner,
    tier: service.tier,
    exposure: service.exposure,
  }
}

matrix_entry_for = |service: ServiceDef| -> MatrixEntry {
  return {
    service: service.name,
    owner: service.owner,
    buildCommand: service.buildCommand,
    testCommand: service.testCommand,
  }
}

deployment_for = |service: ServiceDef| -> DeploymentRecord {
  return {
    service: service.name,
    owner: service.owner,
    image: service.image,
    tier: service.tier,
    dependsOn: service.dependsOn ?? [],
  }
}

compose_service_for = |service: ServiceDef| -> ComposeService {
  port = service.port ?? 0

  return {
    image: service.image,
    ports: service.port == null ? [] : [`${port}:${port}`],
    depends_on: service.dependsOn ?? [],
    environment: {
      SERVICE_NAME: service.name,
      SERVICE_TIER: service.tier,
      OWNER_TEAM: service.owner,
    },
  }
}

public_endpoint_for = |service: ServiceDef| -> PublicEndpoint {
  return {
    service: service.name,
    url: `https://${service.name}.example.internal`,
    healthPath: service.healthPath ?? `/health`,
  }
}

summary = services |> map(|service: ServiceDef| summary_for(service))

matrix: Matrix = {
  include: services |> map(|service: ServiceDef| matrix_entry_for(service)),
}

public_endpoints = services
  |> filter(|service: ServiceDef| service.exposure == `public`)
  |> map(|service: ServiceDef| public_endpoint_for(service))

compose: Compose = {
  version: `3.9`,
  services: {
    web: compose_service_for(web),
    api: compose_service_for(api),
    worker: compose_service_for(worker),
    redis: {
      image: `redis:7`,
      ports: [`6379:6379`],
      environment: {
        SERVICE_NAME: `redis`,
        SERVICE_TIER: `cache`,
        OWNER_TEAM: `operations`,
      },
    },
  },
}

deployment_bundle: DeploymentBundle = {
  environment: `staging`,
  services: services |> map(|service: ServiceDef| deployment_for(service)),
}

pub main = || Emit::manifest({
  entries: [
    {
      path: Path::join([`catalog`, `service-summary.json`]),
      format: `json`,
      value: summary,
    },
    {
      path: Path::join([`catalog`, `ci-matrix.json`]),
      format: `json`,
      value: matrix,
    },
    {
      path: Path::join([`catalog`, `public-endpoints.json`]),
      format: `json`,
      value: public_endpoints,
    },
    {
      path: Path::join([`compose`, `docker-compose.yml`]),
      format: `yaml`,
      value: compose,
    },
    {
      path: Path::join([`deploy`, `staging-services.yaml`]),
      format: `yaml`,
      value: deployment_bundle,
    },
  ]
})
```

## Output

Running the example with `--file-root` writes:

- `catalog/service-summary.json`
- `catalog/ci-matrix.json`
- `catalog/public-endpoints.json`
- `compose/docker-compose.yml`
- `deploy/staging-services.yaml`

```json
{
  "include": [
    {
      "service": "web",
      "owner": "web-platform",
      "buildCommand": "npm run build -w web",
      "testCommand": "npm test -w web"
    },
    {
      "service": "api",
      "owner": "payments",
      "buildCommand": "npm run build -w api",
      "testCommand": "npm test -w api"
    },
    {
      "service": "worker",
      "owner": "operations",
      "buildCommand": "npm run build -w worker",
      "testCommand": "npm test -w worker"
    }
  ]
}
```

## Key concepts

- **Single typed catalog** keeps ownership, deployment, and CI metadata in one source of truth.
- **Collection transforms** derive summaries, CI inputs, and public endpoint data with `map` and `filter` instead of repeating hand-maintained files.
- **Mixed artifact emission** uses one Rank program to generate both JSON and YAML outputs.
- **Compose and deployment views** are projections of the same catalog, not separate config trees that can drift.

## Run it

```sh
rank examples/service-catalog --file-root out/service-catalog
```

---

## Static Site Deploy Plan


Describe a static site once and emit upload metadata, redirects, and a deploy plan from the same typed source.

## Source

```rank title="examples/static-site-deploy-plan/types.rank"
pub Page = Object {
  path: string,
  source: string,
  cachePolicy: `short` | `long`,
}

pub Redirect = Object {
  from: string,
  to: string,
  status: 301 | 302,
}

pub UploadEntry = Object {
  key: string,
  source: string,
  cacheControl: string,
}
```

```rank title="examples/static-site-deploy-plan/main.rank"
/// Generates a static-site deployment bundle from typed page and redirect data.
/// Shows one content model driving routing, caching, and upload planning.

use std::Emit
use std::Path
use std::collections::{ map }
use root::types::{ Page, Redirect, UploadEntry }

pages: [Page] = [
  {
    path: `/`,
    source: `dist/index.html`,
    cachePolicy: `short`,
  },
  {
    path: `/pricing`,
    source: `dist/pricing/index.html`,
    cachePolicy: `short`,
  },
  {
    path: `/assets/app.js`,
    source: `dist/assets/app.93d2.js`,
    cachePolicy: `long`,
  },
  {
    path: `/assets/styles.css`,
    source: `dist/assets/styles.a12c.css`,
    cachePolicy: `long`,
  },
]

redirects: [Redirect] = [
  {
    from: `/docs`,
    to: `/pricing`,
    status: 302,
  },
  {
    from: `/home`,
    to: `/`,
    status: 301,
  },
]

cache_control_for = |page: Page| -> string {
  return match page.cachePolicy {
    `short` => `public, max-age=60, stale-while-revalidate=300`,
    `long` => `public, max-age=31536000, immutable`,
  }
}

upload_entry_for = |page: Page| -> UploadEntry {
  key = page.path == `/` ? `index.html` : page.path

  return {
    key: key,
    source: page.source,
    cacheControl: cache_control_for(page),
  }
}

upload_manifest = pages |> map(|page: Page| upload_entry_for(page))

deployment_plan = {
  bucket: `rank-static-site`,
  invalidatePaths: pages
    |> map(|page: Page| page.path),
  uploadCount: 4,
}

pub main = || Emit::manifest({
  entries: [
    {
      path: Path::join([`site`, `uploads.json`]),
      format: `json`,
      value: upload_manifest,
    },
    {
      path: Path::join([`site`, `redirects.json`]),
      format: `json`,
      value: redirects,
    },
    {
      path: Path::join([`site`, `deployment-plan.json`]),
      format: `json`,
      value: deployment_plan,
    },
  ]
})
```

## Output

Running the example with `--file-root` writes:

- `site/uploads.json`
- `site/redirects.json`
- `site/deployment-plan.json`

## Run it

```sh
npm run rank -- examples/static-site-deploy-plan --file-root out/static-site-deploy-plan
```

## Key concepts

- A typed page list controls cache headers, upload keys, and CDN invalidation paths.
- Redirect data stays first-class and emits as its own artifact.
- One manifest can describe both file uploads and deployment metadata.

---

## Tenant Config Generator


Drive per-tenant runtime configs and a shared tenant index from one typed tenant list.

## Source

```rank title="examples/tenant-config-generator/types.rank"
pub Plan = `starter` | `growth` | `enterprise`

pub Region = `us-east-1` | `eu-west-1` | `ap-southeast-1`

pub Theme = `blueprint` | `sand` | `forest`

pub Tenant = Object {
  id: string,
  displayName: string,
  plan: Plan,
  region: Region,
  domain: string,
  theme: Theme,
}

pub TenantConfig = Object {
  tenantId: string,
  displayName: string,
  baseUrl: string,
  region: Region,
  plan: Plan,
  features: Object {
    sso: bool,
    auditLogs: bool,
    customDomain: bool,
  },
  branding: Object {
    theme: Theme,
    logoPath: string,
  },
}
```

```rank title="examples/tenant-config-generator/main.rank"
/// Generates per-tenant runtime configs plus a shared routing index.
/// Shows one tenant list driving multiple downstream artifacts.

use std::Emit
use std::Path
use std::collections::{ map }
use root::types::{ Plan, Tenant, TenantConfig }

tenants: [Tenant] = [
  {
    id: `atlas`,
    displayName: `Atlas Health`,
    plan: `starter`,
    region: `us-east-1`,
    domain: `atlas.example.com`,
    theme: `blueprint`,
  },
  {
    id: `helix`,
    displayName: `Helix Manufacturing`,
    plan: `growth`,
    region: `eu-west-1`,
    domain: `helix.example.eu`,
    theme: `sand`,
  },
  {
    id: `nova`,
    displayName: `Nova Payments`,
    plan: `enterprise`,
    region: `ap-southeast-1`,
    domain: `nova.example.io`,
    theme: `forest`,
  },
]

features_for = |plan: Plan| {
  return match plan {
    `starter` => {
      sso: false,
      auditLogs: false,
      customDomain: true,
    },
    `growth` => {
      sso: true,
      auditLogs: false,
      customDomain: true,
    },
    `enterprise` => {
      sso: true,
      auditLogs: true,
      customDomain: true,
    },
  }
}

config_for = |tenant: Tenant| -> TenantConfig {
  return {
    tenantId: tenant.id,
    displayName: tenant.displayName,
    baseUrl: `https://${tenant.domain}`,
    region: tenant.region,
    plan: tenant.plan,
    features: features_for(tenant.plan),
    branding: {
      theme: tenant.theme,
      logoPath: `/branding/${tenant.id}.svg`,
    },
  }
}

tenant_configs = tenants |> map(|tenant: Tenant| config_for(tenant))

index = {
  tenants: tenant_configs |> map(|config: TenantConfig| {
    tenantId: config.tenantId,
    domain: config.baseUrl,
    region: config.region,
    plan: config.plan,
  }),
}

pub main = || Emit::manifest({
  entries: [
    {
      path: Path::join([`tenants`, `atlas.json`]),
      format: `json`,
      value: tenant_configs[0],
    },
    {
      path: Path::join([`tenants`, `helix.json`]),
      format: `json`,
      value: tenant_configs[1],
    },
    {
      path: Path::join([`tenants`, `nova.json`]),
      format: `json`,
      value: tenant_configs[2],
    },
    {
      path: Path::join([`tenants`, `index.json`]),
      format: `json`,
      value: index,
    },
  ]
})
```

## Output

Running the example with `--file-root` writes:

- `tenants/atlas.json`
- `tenants/helix.json`
- `tenants/nova.json`
- `tenants/index.json`

## Run it

```sh
npm run rank -- examples/tenant-config-generator --file-root out/tenant-config-generator
```

## Key concepts

- One typed tenant list drives multiple derived tenant-specific artifacts.
- Feature entitlements are computed from plan once and reused across all outputs.
- Shared data can emit both leaf artifacts and a cross-tenant routing index.

---

## Test Fixtures


Generate a deterministic set of fake user records using the Faker provider and `range` + `map`.

## Source

```rank title="examples/test-fixtures/main.rank"
/// Generates deterministic test fixture data using the Faker provider.
/// Shows Rand::seed for reproducibility, range + map to produce N records,
/// and typed schemas to validate the generated shape.

use faker::{ Generate, UUID, Person, Int }
use faker::types::{ Spec }
use std::list::{ range }
use std::collections::{ map }

User = Object {
  id: string,
  name: string,
  age: number,
}

seed = 42
count = 10

spec: Spec<User> = {
  id: UUID {},
  name: Person { sex: `female` },
  age: Int { min: 18, max: 65 },
}

users: [User] = range(count)
  |> map(|_, ctx| Generate<User> {
       spec,
       seed,
       itemKey: ctx.index,
       locale: `en_US`,
     })

pub main = || {
  count: count,
  users: users,
}
```

## Output

```json
{
  "count": 10,
  "users": [
    { "id": "a1b2c3d4-...", "name": "Alice Johnson", "age": 34 },
    { "id": "e5f6a7b8-...", "name": "Maria Garcia", "age": 27 },
    ...
  ]
}
```

The output is **identical on every run** because `seed` and `itemKey` together fully determine each generated value.

## Key concepts

- **`Spec<T>`** — a typed descriptor that pairs each field of `T` with a Faker generator. The compiler checks that every field is covered.
- **`Generate<T>`** — evaluates a `Spec<T>` with a seed and item key. Different `itemKey` values produce different records; the same key always produces the same record.
- **`range(count) |> map`** — generates indices `[0, 1, ..., count-1]` and maps each to a `Generate` call, passing `ctx.index` as the `itemKey`.
- **`ctx` parameter** — the second argument to `map` callbacks is an iterator context with `index`, `size`, `isFirst`, and `isLast`.

## Run it

```sh
rank examples/test-fixtures
```

Requires the `faker` provider package. See the [Faker Provider](../faker-provider) docs for installation.

---

## Types and Generics


Named type aliases, constrained and defaulted generics, utility types, field annotations on object types, literal unions, and exhaustive `match` expressions.

## Source

```rank title="examples/types-and-generics/main.rank"
/// Demonstrates type aliases, constrained and defaulted generics, utility
/// types, field annotations on object types, literal unions, and exhaustive
/// match expressions.

use std::string::{ isBlank }
use std::types::{ Partial, Pick }

Environment = `dev` | `staging` | `prod`

LogLevel = `debug` | `info` | `warn` | `error`

Result<T> = Object {
  ok: bool,
  data?: T,
  error?: string,
}

Field<T, K extends keyof T = `name`> = T[K]

ServiceConfig = Object {
  @constraint(cond: |self| !isBlank(self))
  name: string,
  env: Environment,
  @constraint(cond: |self| self >= 1)
  replicas: number,
  logLevel: LogLevel,
}

ServiceSummary = Pick<ServiceConfig, `name` | `logLevel`>
ServicePatch = Partial<ServiceConfig>

env: Environment = `staging`

log_level_for = |e: Environment| -> LogLevel {
  return match e {
    `dev` => `debug`,
    `staging` => `info`,
    `prod` => `warn`,
  }
}

replicas_for = |e: Environment| -> number {
  return match e {
    `dev` => 1,
    `staging` => 2,
    `prod` => 5,
  }
}

config: ServiceConfig = {
  name: `api`,
  env: env,
  replicas: replicas_for(env),
  logLevel: log_level_for(env),
}

service_name: Field<ServiceConfig> = config.name
replica_count: Field<ServiceConfig, `replicas`> = config.replicas

summary: ServiceSummary = {
  name: service_name,
  logLevel: config.logLevel,
}

patch: ServicePatch = {
  replicas: replica_count,
}

result: Result<ServiceConfig> = {
  ok: true,
  data: config,
}

pub main = || result
```

## Output

```json
{
  "ok": true,
  "data": {
    "name": "api",
    "env": "staging",
    "replicas": 2,
    "logLevel": "info"
  }
}
```

## Key concepts

- **Union of literals** — `Environment = \`dev\` | \`staging\` | \`prod\`` defines an exact set of allowed values.
- **Generic type** — `Result<T>` parameterizes over any type `T`. The compiler infers `T = ServiceConfig` from usage.
- **Constrained/defaulted generic alias** — ``Field<T, K extends keyof T = `name`>`` restricts `K` to valid keys and lets `Field<ServiceConfig>` omit the trailing key argument.
- **Field annotations on object types** — `ServiceConfig.name` and `ServiceConfig.replicas` carry reusable `@constraint` rules that travel with the type.
- **Utility types preserve field annotations** — `Pick<ServiceConfig, ...>` and `Partial<ServiceConfig>` reuse the original field metadata when those fields survive the transform.
- **Optional field** — `data?: T` means the field may be absent. When present its type is `T`; when absent it reads as `null`.
- **`match` exhaustiveness** — the compiler rejects a `match` that does not cover all variants of a union.

## Run it

```sh
rank examples/types-and-generics
```

---

## Manifest Reference


`rank.toml` is the project manifest for Rank programs, packages, and providers. It declares the source root, dependency and provider registrations, registry aliases, security defaults, provider-package metadata, and git-backed dependency sources.

## Synopsis

Minimal project manifest:

```toml
manifestVersion = 1

[package]
name = "hello-rank"
version = "0.1.0"
source = "src"
```

Project manifest with dependencies, providers, registry aliases, and security defaults:

```toml
manifestVersion = 1

[package]
name = "acme-app"
version = "0.1.0"
source = "src"

[registries]
company = { url = "https://registry.example.com" }

[registryScopes]
"@acme" = "company"

[dependencies]
collections = { registry = "npm", package = "@rank-lang/lib-collections", version = "1.2.0" }
shapes = { path = "./vendor/shapes" }
shared = { git = "https://github.com/acme/shared.git", rev = "8d91b7c4e5d0c1a2b3f4e5d6c7b8a9b0c1d2e3f4" }

[providers]
faker = { registry = "npm", package = "@rank-lang/plugin-faker", version = "0.1.0" }
vault = { path = "./providers/vault" }

[security]
allow-provider-capabilities = ["network"]
allow-http-hosts = ["api.example.com"]
allow-env = ["API_*", "AWS_REGION"]
provider-timeout-ms = 30000
offline = false
```

Provider package manifest:

```toml
manifestVersion = 1

[package]
name = "acme-provider"
version = "0.4.0"
source = "src"

[provider]
namespace = "acme"
runtime = "node"
entry = "./dist/provider.js"

[[provider.exports]]
name = "Lookup"
kind = "backend"
inputSchema = "types::LookupInput"
outputSchema = "types::LookupOutput"
reproducibility = ["service", "key", "cacheKey"]
capabilities = ["network"]
```

---

## File Location And Discovery

The manifest filename is exactly `rank.toml`.

- Project commands walk upward from a file entry until they find `rank.toml`.
- When you pass a directory, Rank resolves `[package].source/main.rank` from that directory's manifest.
- If a directory has no `rank.toml`, the CLI falls back to `./main.rank`.
- Provider packages also use `rank.toml` at the provider package root.
- The language server uses the same upward search to determine the project root.

---

## Top-Level Shape

| Key | Required | Meaning |
|---|---|---|
| `manifestVersion` | Yes | Must be `1`. |
| `[package]` | Yes for project and package roots | Declares package metadata and source root. |
| `[dependencies]` | No | Imported Rank package dependencies. |
| `[providers]` | No | Imported provider registrations. |
| `[registries]` | No | Registry alias to URL mapping. |
| `[registryScopes]` | No | Scope-to-registry defaults for scoped package names. |
| `[security]` | No | Project security defaults merged with CLI flags. |
| `[provider]` | No | Provider-package metadata. |
| `[[provider.exports]]` | Required when `[provider]` exists | Host-implemented exports declared by a provider package. |

---

## `[package]`

Every ordinary project or installable package needs a `[package]` table.

```toml
[package]
name = "inventory"
version = "0.1.0"
source = "src"
```

| Field | Required | Meaning |
|---|---|---|
| `name` | Yes | Package name for humans and registry metadata. |
| `version` | Yes | Package version string. |
| `source` | Yes | Source root directory, resolved relative to the manifest. |

`source` becomes the canonical `root::` module tree for ordinary project imports. If `source = "src"`, then `src/main.rank` is imported as `root::main`.

Inside that project-local module tree, nearby imports may also use contextual relative anchors: `self::...` resolves from the current module namespace, and `super::...` resolves from the parent namespace.

---

## `[dependencies]` And `[providers]`

Dependency and provider entries overlap, but they do not share the exact same reference shape. The table key is the import alias used in Rank source.

Dependencies can be distributed through local paths, npm-compatible registries, or git repositories. Providers can be distributed through local paths or npm-compatible registries. For package publication workflows, see [Dependencies](./dependencies.mdx) and [Provider authoring](/docs/provider-authoring).

Path-based reference:

```toml
[dependencies]
shapes = { path = "./vendor/shapes" }

[providers]
vault = { path = "./providers/vault" }
```

Registry-backed reference:

```toml
[dependencies]
collections = { registry = "npm", package = "@rank-lang/lib-collections", version = "1.2.0" }

[providers]
faker = { registry = "npm", package = "@rank-lang/plugin-faker", version = "0.1.0" }
```

Git-backed dependency reference:

```toml
[dependencies]
shared = { git = "https://github.com/acme/shared.git", rev = "8d91b7c4e5d0c1a2b3f4e5d6c7b8a9b0c1d2e3f4" }
theme = { git = "https://github.com/acme/theme.git", tag = "v1.4.2" }
ui = { git = "ssh://git@github.com/acme/mono.git", rev = "6a1f0d9a8b7c6e5d4c3b2a190817161514131211", subdir = "packages/ui" }
```

Reference rules:

- Each dependency entry must contain exactly one of `path`, `version`, or `git`.
- Each provider entry must contain exactly one of `path` or `version`.
- `path` values are resolved relative to the manifest directory.
- `registry` may only appear on registry-backed entries.
- `package` may only appear on registry-backed entries.
- `git` may appear only under `[dependencies]` in this slice.
- Git-backed dependencies must declare exactly one of `rev` or `tag`.
- `subdir` is optional and may appear only with `git`.
- `subdir` must remain within the fetched repository root after normalization.
- If `package` is omitted, the package name defaults to the table key.
- If `registry` is omitted, Rank uses the default registry; `[registryScopes]` can override that default for scoped package names.
- `[dependencies]` aliases define imported package namespaces such as `shapes::...`.
- `[providers]` aliases define imported provider namespaces such as `faker::...`.
- For providers, the alias should match the provider package's `[provider].namespace`.

### Git dependency lock and cache behavior

- `{ git, rev }` treats `rev` as the initial resolved identity, but Rank still writes `requestedRev` and `resolvedRev` to `rank.lock`.
- `{ git, tag }` resolves the tag to a commit and writes `requestedTag` and `resolvedRev` to `rank.lock`.
- `rank sync`, `rank check`, `rank deps`, and ordinary evaluation reuse the locked commit and cached snapshot after the first successful materialization.
- `--frozen-lockfile` rejects any git dependency that does not already have a matching lock entry.
- `--offline` requires both a matching lock entry and a cached snapshot for every git dependency.

### Dependency vs provider

A dependency is a regular Rank package. Rank loads its `.rank` source modules from that package's `[package].source` tree, and you use it for pure reusable code such as types, helper functions, transforms, and shared schemas.

A provider is a host extension. In addition to the ordinary package manifest, it also declares `[provider]` and `[[provider.exports]]` metadata for host-implemented operations. Use a provider when the package needs capabilities or behavior that ordinary Rank source cannot provide by itself, such as external backends, network calls, filesystem access, or commit-time mutations.

In practice:

- dependencies are library code
- providers are manifest-declared host operations
- dependencies do not have a provider runtime entrypoint or capability surface
- providers do have a runtime entrypoint, export metadata, and capability/security controls
- provider packages may still ship ordinary `.rank` modules alongside their provider exports

---

## `[registries]`

`[registries]` defines named registry aliases.

```toml
[registries]
company = { url = "https://registry.example.com" }
```

| Field | Required | Meaning |
|---|---|---|
| `url` | Yes | Base URL for the registry alias. |

Use registry aliases from dependency or provider references:

```toml
[dependencies]
ui = { registry = "company", package = "@acme/ui", version = "1.4.0" }
```

---

## `[registryScopes]`

`[registryScopes]` maps npm-style package scopes to registry aliases.

```toml
[registryScopes]
"@acme" = "company"
```

This lets a scoped package pick up a registry alias automatically when the reference omits `registry`:

```toml
[dependencies]
ui = { package = "@acme/ui", version = "1.4.0" }
```

With the scope mapping above, Rank resolves `@acme/ui` through the `company` registry alias.

---

## `rank.lock`

External dependency materialization writes `rank.lock`. Registry-backed packages, providers, and git-backed dependencies all use the same explicit version-2 lockfile envelope.

```toml
version = 2

[[packages]]
kind = "registry"
registry = "npm"
registryUrl = "https://registry.npmjs.org"
package = "@rank-lang/lib-collections"
requestedVersion = "1.2.0"
resolvedVersion = "1.2.0"
resolvedTarballUrl = "https://registry.npmjs.org/@rank-lang/lib-collections/-/lib-collections-1.2.0.tgz"
integrity = "sha512-..."

[[packages]]
kind = "git"
git = "https://github.com/acme/theme.git"
requestedTag = "v1.4.2"
resolvedRev = "4e8d2c4c9b7a6d5e1f3c2a190817161514131211"

[[packages]]
kind = "git"
git = "ssh://git@github.com/acme/mono.git"
requestedRev = "6a1f0d9a8b7c6e5d4c3b2a190817161514131211"
resolvedRev = "6a1f0d9a8b7c6e5d4c3b2a190817161514131211"
subdir = "packages/ui"
```

Lockfile rules:

- Registry entries use `kind = "registry"` and record the resolved tarball identity.
- Git entries use `kind = "git"` and record the requested selector plus the concrete `resolvedRev` used for loading.
- `rank.lock` is part of the reproducibility contract. Commit it alongside `rank.toml`.
- `rank sync` is the explicit prefetch workflow for writing or refreshing lock entries without evaluating the entrypoint.

---

## `[security]`

`[security]` stores project defaults for the same security controls exposed by CLI flags.

```toml
[security]
allow-provider-capabilities = ["network"]
allow-provider-mutation-exports = ["aws::PutObject"]
allow-http-hosts = ["api.example.com"]
allow-env = ["API_*", "AWS_REGION"]
provider-timeout-ms = 30000
offline = false
```

| Field | Type | Meaning |
|---|---|---|
| `allow-provider-capabilities` | `[string]` | Provider capability allowlist. Standardized values include `network` and `filesystem`. |
| `allow-provider-mutation-exports` | `[string]` | Exact-name allowlist for reachable `mutation` provider exports. |
| `allow-http-hosts` | `[string]` | Static host allowlist for `HTTP::Fetch`. |
| `allow-env` | `[string]` | Runtime environment-variable allowlist for serve startup `Env<T>` and request-time providers. |
| `provider-timeout-ms` | `number` | Non-negative timeout in milliseconds for provider invocations. |
| `offline` | `bool` | Reuse cached artifacts only; block live network fetches. |

Merge behavior:

- Additive settings are unioned with CLI flags.
- Scalar settings use CLI values when provided.
- For runtime-bearing hosts, omitting `allow-env` yields an empty admitted environment view.
- A bare `"*"` in `allow-env` is the explicit allow-all escape hatch and should be used deliberately.

---

## `[provider]`

Provider packages use the same root manifest and add a `[provider]` table.

```toml
[provider]
namespace = "greeter"
runtime = "node"
entry = "./src/provider.js"
```

| Field | Required | Meaning |
|---|---|---|
| `namespace` | Yes | Namespace Rank programs import, such as `use greeter::{ Greet }`. |
| `runtime` | Yes | One of `native`, `node`, `deno`, or `bun`. |
| `entry` | Yes | Provider runtime entry point, resolved relative to the manifest. |

When `[provider]` is present, the manifest must also declare one or more `[[provider.exports]]` entries.

---

## `[[provider.exports]]`

Each `[[provider.exports]]` block declares one host-implemented export.

```toml
[[provider.exports]]
name = "Lookup"
kind = "function"
typeParameters = ["T", "K extends keyof T = `id`"]
inputSchema = "types::LookupInput<T, K>"
outputSchema = "T[K]"
capabilities = []
```

| Field | Required | Meaning |
|---|---|---|
| `name` | Yes | Public export name. |
| `kind` | Yes | One of `backend`, `function`, or `mutation`. |
| `typeParameters` | No | Generic parameter clauses declared by this export. Each entry uses `Name`, `Name extends Type`, `Name = Type`, or `Name extends Type = Default`. |
| `inputSchema` | Yes | Input type expression in the provider package namespace. |
| `outputSchema` | Yes | Output type expression in the provider package namespace. |
| `capabilities` | Yes | Declared provider capabilities. |
| `reproducibility` | Required for `backend` | Explicit reproducibility metadata for backend exports. |
| `fulfillmentField` | Required for `mutation` | Top-level input field fulfilled later by the mutation commit path. |

Kind-specific rules:

- `backend` exports must declare `reproducibility`.
- `function` exports must declare `capabilities = []`.
- `function` exports may not declare `reproducibility` or `fulfillmentField`.
- `mutation` exports must declare `fulfillmentField`.
- `mutation` exports may not declare `reproducibility`.
- `typeParameters`, when present, may not contain duplicates.
- Later `typeParameters` entries may reference earlier parameters in bounds and defaults.
- Defaulted `typeParameters` entries must stay trailing so omitted type arguments form a suffix.

---

## Resolution Rules

- `rank.toml` is versioned, source-controlled project state. Treat it as part of the program, not as an incidental local config file.
- All manifest-relative paths are resolved from the directory that contains the manifest.
- Registry-backed dependencies and providers, plus git-backed dependencies, participate in `rank sync`, `rank.lock`, `--offline`, and `--frozen-lockfile` workflows.
- Provider packages may combine ordinary `pub` source modules under `[package].source` with host-implemented exports declared in `[[provider.exports]]`.

See also:

- [CLI Reference](./cli.mdx)
- [Dependencies](./dependencies.mdx)
- [Project Structure](./project-structure.mdx)
- [Provider Guide](./faker-provider.mdx)
- [Provider authoring](/docs/provider-authoring)

---

## CLI Reference


The `rank` CLI compiles, checks, tests, syncs, and serves Rank programs.

If you are new to Rank, start with [Getting Started](./getting-started.mdx) first. Use this page as the command reference once you are already building configs, manifests, tests, or HTTP apps.

For generated outputs, see [Output and manifests](./language/output.mdx). For HTTP apps, see [HTTP Server](./server.mdx).

## Synopsis

```sh
rank [entry-or-dir] [options]                 # evaluate and emit (default: YAML; use --format json for JSON)
rank check <entry-or-dir>                     # type-check only, no output
rank test <path> [options]                    # run rank-test.json cases
rank deps <entry-or-dir> [options]            # list dependencies
rank serve <entry-or-dir> [options]           # start the server runtime
rank sync <entry-or-dir> [options]            # fetch and cache registry dependencies
```

---

## `rank [entry-or-dir]` — evaluate and emit

Evaluates the program at the requested entry and writes the result to stdout. This is the primary workflow for producing output.

For ordinary document results, `rank` emits YAML by default and accepts `--format json` for JSON output. If `pub main` returns `Emit::manifest(...)`, stdout contains the descriptor envelope for that manifest in the selected format. See [Output and manifests](./language/output.mdx).

```sh
rank src/main.rank
rank examples/faker-dataset
rank examples/faker-dataset --file-root out/
cd examples/faker-dataset && rank
```

`entry-or-dir` may be either a `.rank` source file or a project directory.

- If you pass a file, the compiler resolves its project manifest (`rank.toml`) by walking up from the file's directory.
- If you pass a directory, the CLI first looks for `rank.toml` in that directory and resolves `[package].source/main.rank`.
- If the directory has no `rank.toml`, the CLI falls back to `./main.rank`.
- If the directory has `rank.toml` but the manifest is invalid, the CLI surfaces manifest diagnostics instead of falling back.
- Running bare `rank` from a directory that contains `rank.toml` is equivalent to `rank .`.

### Flags

| Flag | Description |
|---|---|
| `--format yaml|json` | Select stdout format for ordinary document output and manifest descriptor envelopes. Defaults to `yaml`. |
| `--file-root <path>` | Root directory for materializing a multi-file `Emit::manifest(...)` result. |
| `--http-cache <path>` | Load HTTP snapshot cache from `<path>` (a `rank/http-cache` JSON document). Cached responses are replayed instead of making live requests. |
| `--write-http-cache <path>` | Write a new HTTP snapshot cache to `<path>` after evaluation. Creates or overwrites the file. |
| `--trace-eval-log <path>` | Write newline-delimited JSON evaluation trace events to `<path>` while keeping stdout reserved for the evaluated result. Creates parent directories and truncates the file at the start of each run. |
| `--emit-sensitive` | When trace output is enabled, allow sensitive values to appear in emitted trace diagnostics and previews instead of `<sensitive>`. Requires `--trace-eval-log <path>`. Use only in trusted local debugging environments. |
| `--allow-provider-capability <name>` | Opt in to a declared provider capability. May be repeated. Use `network` to allow network-capable providers. |
| `--offline` | Reuse only locally cached registry artifacts. Fails if any required package is not yet cached. |
| `--frozen-lockfile` | Refuse to resolve missing `rank.lock` entries. Useful in CI to enforce that the lockfile is up to date. |

### Examples

Emit the default YAML result:

```sh
rank src/main.rank
```

Emit the same result as JSON:

```sh
rank src/main.rank --format json
```

Emit with an HTTP snapshot cache for reproducible output:

```sh
rank src/main.rank --http-cache snapshots.json
```

Capture a fresh HTTP snapshot:

```sh
rank src/main.rank --write-http-cache snapshots.json
```

Write a structured evaluation trace to a log file without changing stdout:

```sh
rank src/main.rank --trace-eval-log .rank/eval.ndjson
```

Evaluate a program that uses a network-capable provider:

```sh
rank src/main.rank --allow-provider-capability network
```

Write a multi-file manifest to a directory:

```sh
rank src/main.rank --file-root ./output
```

---

## `rank check` — type-check only

Parses, resolves, and type-checks the program. Produces no output on success. Exits with a non-zero code and prints diagnostics on failure.

```sh
rank check src/main.rank
rank check testdata/modules/package-path-import
```

Use this in CI or as a pre-commit step to validate programs without running them. The argument may be either an entry file or a project directory; directory inputs resolve the same way as the run command.

In the packaged CLI, this remains a compile-only command. If you are developing from this repository with `npm run rank -- ...`, see [Development shortcut](#development-shortcut) for the current caveat around external-input examples.

### Flags

| Flag | Description |
|---|---|
| `--allow-provider-capability <name>` | Same as the run command — needed when checking programs that declare provider dependencies with capabilities. |
| `--offline` | Reuse only locally cached registry artifacts. |
| `--frozen-lockfile` | Refuse to resolve missing `rank.lock` entries. |

### Exit codes

| Code | Meaning |
|---|---|
| `0` | No errors |
| `1` | One or more diagnostics |

---

## `rank test` — run lightweight unit tests

Runs one public-style test case directory or recursively discovers all `rank-test.json` cases under a suite directory.

```sh
rank test examples/tests
rank test examples/tests --filter env
rank test examples/tests/external-inputs --format json
rank test examples/tests/yaml-expected --format yaml
```

Each case directory contains a `rank-test.json` manifest plus an entry module and optional deterministic input snapshots such as `env.json` or `http.json`.

### Flags

| Flag | Description |
|---|---|
| `--filter <pattern>` | Run only cases whose discovered name or path contains `<pattern>`. |
| `--format text\|json\|yaml` | Output format. `text` (default) prints pass/fail lines. `json` and `yaml` emit a structured `rank/test-report` document. |
| `--offline` | Reuse only locally available registry artifacts while loading any package dependencies used by test cases. |
| `--frozen-lockfile` | Refuse to resolve missing registry lock entries while loading any package dependencies used by test cases. |

### Examples

Run the full sample suite:

```sh
rank test examples/tests
```

Run only the env-focused cases:

```sh
rank test examples/tests --filter env
```

Get a machine-readable report for one case:

```sh
rank test examples/tests/external-inputs --format json
```

Get the same structured report as YAML:

```sh
rank test examples/tests/yaml-expected --format yaml
```

### Case layout

Minimal pure value case:

```text
examples/tests/pure-addition/
	rank-test.json
	expected.json
	src/
		main.rank
```

Minimal manifest:

```json
{
	"kind": "rank/test-case",
	"version": 1,
	"entry": "src/main.rank",
	"expectedValue": "expected.json"
}
```

`expectedValue` may point to `expected.json`, `expected.yaml`, or `expected.yml`.

Cases may also include:

- `env.json` for deterministic `Env<T> {}` inputs
- `http.json` for deterministic `HTTP::Fetch<T> {}` inputs
- a local `rank.toml` plus `providers/` directory for deterministic path-based provider imports
- `provider-stubs.json` plus `"providerStubs": "provider-stubs.json"` for deterministic backend provider outputs keyed by public export name and exact full input
- `expectedDiagnostics` arrays instead of `expectedValue`, where each matcher uses `code` plus either exact `message` or partial `messageContains`

When `pub main` returns `Emit::manifest(...)`, `expectedValue` should contain the descriptor envelope in JSON form:

```json
{
	"kind": "rank/output-manifest",
	"version": 1,
	"entries": [
		{
			"path": "README.md",
			"format": "text",
			"value": "# api\n"
		}
	]
}
```

Backend provider stubs use a small JSON object keyed by public provider export name:

```json
{
	"api::users::lookup": [
		{
			"input": {
				"id": "123",
				"cacheKey": "lookup-123"
			},
			"output": {
				"name": "stubbed-user-123"
			}
		}
	]
}
```

Each stub entry matches the backend provider call by exact full input. Backend provider invocations without a matching stub fail inside `rank test` instead of falling through to a live runtime call.

The sample cases under `examples/tests/` show pure-value, YAML-expected, manifest-output, local provider, backend-provider-stub, diagnostic, environment, and combined file plus HTTP snapshot workflows.

For a more complete testing workflow guide, including provider stubs and suite layout, see [Unit Testing](./testing.mdx).

---

## `rank deps` — list dependencies

Reports all static dependencies of the program: imported modules, provider namespaces, environment variable reads, file reads, and HTTP fetch nodes.

```sh
rank deps src/main.rank
rank deps testdata/modules/provider-function-import
rank deps src/main.rank --format json
rank deps src/main.rank --format json --explain <id>
```

The argument may be either an entry file or a project directory; directory inputs resolve the same way as the run command.

### Flags

| Flag | Description |
|---|---|
| `--format text\|json` | Output format. `text` (default) prints a human-readable report. `json` emits a `rank/dependency-report` document. |
| `--explain <id>` | Resolve a single graph node or dependency ID back to its dependency path from the entry node. Requires `--format json`. |
| `--allow-provider-capability <name>` | Same as the run command — needed when checking programs that declare provider dependencies with capabilities. |

### Examples

Print a human-readable dependency report:

```sh
rank deps src/main.rank
```

Get a structured JSON report:

```sh
rank deps src/main.rank --format json
```

Explain why a specific node is a dependency:

```sh
rank deps src/main.rank --format json --explain env:APP_ENV
```

---

## `rank serve` — server runtime

Starts the HTTP server runtime for a Rank app. The server compiles the entry module and evaluates `pub main` for each inbound request.

```sh
rank serve src/handler.rank
rank serve examples/serve-docker
rank serve src/handler.rank --port 3000
rank serve src/handler.rank --host 0.0.0.0 --port 8080
rank serve src/handler.rank --dev
```

The argument may be either an entry file or a project directory; directory inputs resolve the same way as the run command.

See the [HTTP Server guide](./server) for a full walkthrough of routes, responses, auth, and deployment.

### Flags

| Flag | Description |
|---|---|
| `--host <host>` | Interface to bind. Defaults to `127.0.0.1`. Use `0.0.0.0` to listen on all interfaces (required in Docker). |
| `--port <port>` | Port to listen on. Defaults to `3000`. |
| `--shutdown-grace-ms <ms>` | Grace period in milliseconds after receiving `SIGINT`/`SIGTERM` before forcibly closing connections. Defaults to `0`. |
| `--dev` | Enable development mode. |
| `--trace-eval` | Stream newline-delimited JSON evaluation trace events to stdout for startup and request-time evaluation. |
| `--emit-sensitive` | When trace output is enabled, allow sensitive values to appear in emitted trace diagnostics and previews instead of `<sensitive>`. Requires `--trace-eval`. Use only in trusted local debugging environments. |
| `--provider-timeout <ms>` | Timeout in milliseconds for provider invocations. |
| `--allow-provider-capability <name>` | Opt in to a declared provider capability. May be repeated. Use `network` to allow network-capable providers. |
| `--allow-http-host <host>` | Allowlist a specific host for outbound `HTTP::Fetch` calls made at serve time. May be repeated. |
| `--allow-env <pattern>` | Allowlist an environment variable name or glob pattern for `Env<T>` reads. May be repeated. |
| `--offline` | Reuse only locally cached registry artifacts. |
| `--frozen-lockfile` | Refuse to resolve missing `rank.lock` entries. |

### Examples

Start with default host and port:

```sh
rank serve src/handler.rank
```

Bind to all interfaces on port 8080 (typical inside Docker):

```sh
rank serve . --host 0.0.0.0 --port 8080
```

Allow outbound HTTP fetches to a specific host and read an environment variable:

```sh
rank serve . --allow-http-host api.example.com --allow-env API_KEY
```

Allow a network-capable provider and set a graceful shutdown window:

```sh
rank serve . --allow-provider-capability network --shutdown-grace-ms 5000
```

Stream structured evaluation traces for live requests:

```sh
rank serve . --trace-eval
```

For guidance on reading trace output and combining it with request-time failures, see [Debugging](./debugging.mdx).

### Built-in readiness endpoint

The server exposes `/.well-known/rank/ready` independently of the application route table. It returns `200 OK` once the runtime is ready to accept traffic. Use this path for load balancer health checks or the Lambda Web Adapter `READINESS_CHECK_PATH` configuration.

---

## `rank sync` — fetch and cache external dependencies

Resolves external dependencies declared in `rank.toml`, materializes any missing registry artifacts or git snapshots, and writes or updates `rank.lock`. No program is evaluated — this command only performs dependency materialization.

In the current slice, this includes registry-backed dependencies, registry-backed providers, and git-backed dependencies. Providers remain path- or registry-backed only.

```sh
rank sync src/main.rank
rank sync path/to/project
```

This is useful as an explicit pre-fetch step in CI or Docker builds before running in offline mode. For `{ git, tag }` dependencies, `rank sync` resolves the tag to a commit and records that commit in `rank.lock`. The argument may be either an entry file or a project directory; directory inputs resolve the same way as the run command.

### Flags

| Flag | Description |
|---|---|
| `--offline` | Reuse only locally cached registry artifacts and git snapshots. Fails if any required package or snapshot is missing. |
| `--frozen-lockfile` | Refuse to resolve missing `rank.lock` entries. Useful for verifying that `rank.lock` is committed and up to date. |

### Examples

Pre-fetch registry packages and git-backed dependencies:

```sh
rank sync src/main.rank
```

Verify the lockfile is up to date without fetching:

```sh
rank sync src/main.rank --frozen-lockfile
```

Run subsequent commands offline after a successful sync:

```sh
rank sync src/main.rank
rank src/main.rank --offline
```

---

## Global behavior

### Diagnostics

All diagnostic output goes to stderr. On success, stdout contains only the command result: YAML for `rank`, the manifest descriptor envelope for `Emit::manifest(...)`, or the selected text/JSON/YAML format for commands such as `test` and `deps`. This makes it safe to pipe command output directly:

```sh
rank deps src/main.rank --format json | jq '.'
```

### Entry resolution

When the CLI receives a file entry, the compiler locates the project manifest by walking up from that file's directory until it finds a `rank.toml`. The manifest's `source` field determines the module root.

When the CLI receives a directory entry, it resolves that directory first:

- if `rank.toml` is present, the CLI resolves `[package].source/main.rank`
- if `rank.toml` is absent, the CLI falls back to `./main.rank`
- if `rank.toml` is present but invalid, the CLI reports manifest diagnostics instead of falling back

Bare `rank` uses the same directory resolution as `rank .` when the current working directory contains `rank.toml`.

### Provider capabilities

Provider capability enforcement is a compile-side allowlist check. A provider that declares the `network` capability requires `--allow-provider-capability network` at the call site or the invocation is blocked. This makes capability use explicit and auditable in CI scripts.

---

## Development shortcut

When working from the repository source tree, run the CLI without a prior build:

```sh
npm run rank -- check src/main.rank
npm run rank -- src/main.rank
```

:::note Repository source-tree caveat
`npm run rank -- check <entry>` is still the fastest syntax and type pass while developing inside this repo, but examples that use `Env<T>`, `File::Read`, `HTTP::Fetch`, or providers should also be confirmed with `npm run rank -- <entry>` or `npm run rank -- serve <dir>`.

The current dev-path `check` command can still surface browser-host external-input errors such as `Browser evaluation does not support std::Env` even when the packaged CLI and real serve runtime compile the same program successfully.
:::

---

## HTTP Server


Rank programs can run as long-lived HTTP servers. The `rank serve` command compiles the entry module and starts a listener that evaluates `pub main` for each incoming request.

Use this page when you want typed HTTP routes, request narrowing, and provider-backed handlers inside `rank serve`. If you only need generated files or manifests, start with [Introduction](./intro.mdx) or [Examples](./examples/index.mdx) instead.

For deployment-oriented server examples, see [Serve — Docker](./examples/serve-docker.mdx), [Serve — Lambda](./examples/serve-lambda.mdx), and [S3 Logs](./examples/s3-logs.mdx).

## Quick start

```rank title="main.rank"
use std::HTTP
use std::Runtime

HealthRoute = HTTP::Route {
  method: `GET`,
  path: `/health`
}

Routes = HealthRoute

pub main = |req: Runtime::ExecutionContext<Routes>| -> HTTP::Response {
  return {
    status: 200,
    body: { ok: true }
  }
}
```

```sh
rank serve .
# Listening on http://127.0.0.1:3000
```

```sh
curl http://127.0.0.1:3000/health
# {"ok":true}
```

The compiled program must export:

- `pub main` — a function that accepts a `Runtime::ExecutionContext<Routes>` and returns an `HTTP::Response` (or an inlined object with `status` and `body`).

---

## Defining routes

Routes are named type aliases that describe a single HTTP endpoint.

```rank
use std::HTTP

GetUsersRoute = HTTP::Route {
  method: `GET`,
  path: `/users`
}
```

Union them together to form the route set:

```rank
Routes = GetUsersRoute | CreateUserRoute | DeleteUserRoute
```

Pass `Routes` as the type argument to `Runtime::ExecutionContext<Routes>` so the type checker can narrow the context inside each `match` arm.

### Supported methods

Any standard HTTP method string: `` `GET` ``, `` `POST` ``, `` `PUT` ``, `` `PATCH` ``, `` `DELETE` ``, `` `HEAD` ``, `` `OPTIONS` ``.

### Literal paths

```rank
IndexRoute = HTTP::Route { method: `GET`, path: `/` }
AdminRoute = HTTP::Route { method: `GET`, path: `/admin/dashboard` }
```

### Path parameters

Use the `match` prefix with `{name:Type}` placeholders to declare typed path parameters:

```rank
use std::Regex

@constraint(cond: |id| Regex::matches(id, re`^[a-z0-9_-]+$`) )
UserId = string

UserRoute = HTTP::Route {
  method: `GET`,
  path: match`/users/{id:UserId}`
}
```

Inside the handler the `params` field is narrowed to `{ id: UserId }`:

```rank
pub main = |req: Runtime::ExecutionContext<UserRoute>| -> HTTP::Response {
  return {
    status: 200,
    body: { id: req.params.id }
  }
}
```

### Query parameters

Declare the expected query schema with an `Object` type. All fields are optional unless explicitly required:

```rank
SearchRoute = HTTP::Route {
  method: `GET`,
  path: `/search`,
  query: Object {
    q: string,
    limit?: number,
    offset?: number
  }
}
```

Inside the handler `req.query` is narrowed to the declared schema. Optional fields have type `T | null` when not present.

### Request body

Declare the body schema for routes that accept a payload:

```rank
CreateUserRoute = HTTP::Route {
  method: `POST`,
  path: `/users`,
  body: Object {
    name: string,
    email: string,
    active?: bool
  }
}
```

`req.body` is the parsed, type-checked body. For routes without a `body` field, `req.body` is `null`.

### Request headers and cookies

Declare the headers or cookies your handler needs to read:

```rank
InspectRoute = HTTP::Route {
  method: `GET`,
  path: `/inspect`,
  headers: Object {
    accept: string,
    x-trace-id?: string
  },
  cookies: Object {
    session: string
  }
}
```

Fields declared in `headers` and `cookies` are validated on every inbound request. Missing required fields produce a `400` response before the handler runs.

---

## The execution context

`Runtime::ExecutionContext<Routes>` is the type of the value passed to `pub main`. Its fields depend on which arm of the route union is active.

| Field | Type | Description |
|---|---|---|
| `method` | `string` | HTTP method of the request |
| `path` | `string` | Request path |
| `params` | `Object` | Named path parameters (narrowed per route) |
| `query` | `Object` | Parsed query parameters (narrowed per route) |
| `body` | `T \| null` | Parsed request body, or `null` |
| `headers` | `Object` | Declared request headers (narrowed per route) |
| `cookies` | `Object` | Declared cookies (narrowed per route) |
| `auth` | `Principal \| null` | Resolved auth principal when the route declares auth |
| `ctx` | `Object` | Request metadata (see below) |

`ctx` fields:

| Field | Type | Description |
|---|---|---|
| `ctx.request_id` | `string` | Unique identifier for the request |
| `ctx.time_received` | `string` | RFC 3339 timestamp when the request arrived |

### Narrowing with match

When `Routes` is a union, use `match` to narrow `req` to a specific route's context:

```rank
Routes = HealthRoute | StatusRoute | UserRoute

pub main = |req: Runtime::ExecutionContext<Routes>| -> HTTP::Response {
  return match req {
    HealthRoute => { status: 200, body: { ok: true } },
    StatusRoute => { status: 200, body: { verbose: req.query.verbose } },
    UserRoute   => { status: 200, body: { id: req.params.id } },
  }
}
```

The compiler enforces that all arms are covered. Each arm receives a fully narrowed context — `req.params.id` is only accessible inside the `UserRoute` arm.

---

## Responses

`pub main` returns an `HTTP::Response` (or an inline object with the same shape):

```rank
HTTP::Response = Object {
  status: number,
  body: unknown,
  format?: `json` | `yaml` | `text`,
  headers?: Object { ...: string },
  cookies?: [HTTP::SetCookie],
}
```

| Field | Required | Description |
|---|---|---|
| `status` | yes | HTTP status code |
| `body` | yes | Response body value. For `json` and `yaml`, this may be an ordinary document value or a top-level `std::Emit<T>` descriptor. |
| `format` | no | Serialization format. Inherits from `pub config` when omitted. Default: `json` |
| `headers` | no | Additional response headers |
| `cookies` | no | Cookies to set on the response |

### Response formats

- `json` — serializes `body` as JSON. The default. Top-level `std::Emit<T>` bodies are realized first.
- `yaml` — serializes `body` as YAML. Top-level `std::Emit<T>` bodies are realized first.
- `text` — writes `body` as a plain string. Requires `body` to be a `string`.

This is especially useful with `Mutation::commit(...)`: the handler can return commit-aware output directly in `HTTP::Response.body`, and the projected receipt metadata is realized before the server serializes the response.

```rank
pub main = |req: Runtime::ExecutionContext<Routes>| -> HTTP::Response {
  return match req {
    JsonRoute => { status: 200, body: { ok: true } },
    TextRoute => { status: 200, format: `text`, body: `pong` },
  }
}
```

### Setting cookies

Use `HTTP::SetCookie` in the `cookies` list to set response cookies:

```rank
HTTP::SetCookie = Object {
  name: string,
  value: string,
  http_only?: bool,
  secure?: bool,
  same_site?: `Lax` | `Strict` | `None`,
  path?: string,
  domain?: string,
  max_age?: number,
  expires?: string,
}
```

```rank
pub main = |req: Runtime::ExecutionContext<Routes>| -> HTTP::Response {
  return {
    status: 200,
    body: { ok: true },
    cookies: [
      {
        name: `session`,
        value: `tok_abc123`,
        http_only: true,
        secure: true,
        same_site: `Lax`
      }
    ]
  }
}
```

---

## Server configuration

Export a `pub config` binding to control server-level behavior. It must be an object literal or a zero-argument function:

```rank
pub config = {
  allowedOrigins: [`https://app.example.com`],
  allowCredentials: true,
  defaultResponseFormat: `json`,
  maxRequestBodyBytes: 1048576,
  requestTimeoutMs: 30000
}
```

Or as a zero-argument function (useful when the config depends on computed values):

```rank
pub config = || {
  defaultResponseFormat: `json`
}
```

`HTTP::AppConfig` fields:

| Field | Type | Default | Description |
|---|---|---|---|
| `allowedOrigins` | `[string]` | `[]` | CORS allowed origins. `*` permits all origins |
| `allowCredentials` | `bool` | `false` | Set `Access-Control-Allow-Credentials: true` |
| `defaultResponseFormat` | `json\|yaml\|text` | `json` | Format used when a route response omits `format` |
| `maxRequestBodyBytes` | `number` | `1048576` (1 MB) | Maximum inbound body size |
| `requestTimeoutMs` | `number` | `30000` | Per-request timeout in milliseconds |

---

## Authentication

### API key auth

Use `HTTP::ApiKeyAuth<Principal>` to protect a route with an API key. The `verify` function receives the raw token and returns either the resolved principal or an error response:

```rank
use std::Env
use std::HTTP
use std::Runtime

AuthEnv = Object { API_KEY: string, ...: string }
env = Env<AuthEnv> {}

Principal = Object {
  client_id: string,
  scopes: [string]
}

AdminRoute = HTTP::Route {
  method: `GET`,
  path: `/admin`,
  auth: HTTP::ApiKeyAuth<Principal> {
    in: `header`,
    name: `x-api-key`,
    prefix: `Bearer `,
    verify: |token: HTTP::ApiKeyToken| {
      return token.matches(env.API_KEY)
        ? { client_id: `internal`, scopes: [`admin`] }
        : { status: 401, body: { code: `invalid_key` } }
    }
  }
}

Routes = AdminRoute

pub main = |req: Runtime::ExecutionContext<Routes>| -> HTTP::Response {
  return {
    status: 200,
    body: {
      client: req.auth.client_id,
      scopes: req.auth.scopes
    }
  }
}
```

`HTTP::ApiKeyAuth<Principal>` fields:

| Field | Type | Description |
|---|---|---|
| `in` | `` `header` \| `query` `` | Where to read the key |
| `name` | `string` | Header or query parameter name |
| `prefix` | `string` | Token prefix to strip before passing to `verify` (e.g. `` `Bearer ` ``) |
| `verify` | `\|HTTP::ApiKeyToken\| -> Principal \| HTTP::Response` | Validation function |

`HTTP::ApiKeyToken` has one method:

```rank
token.matches(secret: string) -> bool
```

`matches` performs a constant-time comparison to prevent timing attacks. Return an `HTTP::Response` with a non-2xx status from `verify` to reject the request.

When auth succeeds, `req.auth` inside the handler is narrowed to `Principal`. The `verify` function runs before the handler and its result is injected into the context.

---

## Built-in endpoints

The server exposes a readiness endpoint at `/.well-known/rank/ready` that is not part of the application route table. It returns `200 OK` once the runtime is ready to accept traffic. Use this path for load balancer health checks and Lambda Web Adapter `READINESS_CHECK_PATH` configuration.

---

## Deployment

### Plain Docker

```dockerfile title="Dockerfile"
FROM node:22-slim
WORKDIR /app
RUN npm install -g @rank-lang/cli
COPY rank.toml main.rank ./
RUN rank sync .
EXPOSE 3000
CMD ["rank", "serve", ".", "--host", "0.0.0.0", "--port", "3000"]
```

```sh
docker build -t my-rank-app .
docker run --rm -p 3000:3000 my-rank-app
```

Running `rank sync .` during the build step caches all registry dependencies so the container starts without making outbound package requests.

### AWS Lambda (Lambda Web Adapter)

Use a `provided.al2023` custom runtime and attach the Lambda Web Adapter as a layer — no container image required.

```sh title="bootstrap"
#!/bin/sh
export PATH="$LAMBDA_TASK_ROOT/bin:$LAMBDA_TASK_ROOT/node_modules/.bin:$PATH"
exec rank serve "$LAMBDA_TASK_ROOT" --host 0.0.0.0 --port "${PORT:-8080}"
```

```yaml title="template.yaml (SAM)"
Resources:
  RankApp:
    Type: AWS::Serverless::Function
    Properties:
      Runtime: provided.al2023
      Handler: bootstrap
      Layers:
        - !Sub arn:aws:lambda:${AWS::Region}:753240598075:layer:LambdaAdapterLayerX86:24
      Environment:
        Variables:
          PORT: '8080'
          READINESS_CHECK_PATH: /.well-known/rank/ready
```

```sh
sam build --use-container
sam deploy --guided
```

Lambda calls the `bootstrap` executable directly. The Lambda Web Adapter layer translates Lambda invocations into HTTP requests and forwards them to `rank serve` on `PORT`. `READINESS_CHECK_PATH` points to the built-in readiness endpoint so the adapter waits until the server is listening before forwarding traffic.

See the [Serve Docker](./examples/serve-docker) and [Serve Lambda](./examples/serve-lambda) examples for complete runnable projects.

---

## `rank serve` reference

See the [`rank serve` CLI reference](./cli#rank-serve--server-runtime) for the full list of flags including `--host`, `--port`, `--dev`, `--trace-eval`, `--emit-sensitive`, `--allow-http-host`, `--allow-env`, and `--shutdown-grace-ms`. For trace output examples and debugging workflow, see [Debugging](./debugging.mdx).

---

## Unit Testing


Rank ships with a lightweight, deterministic test runner through `rank test`. Use it when you want to pin either the evaluated output or the expected diagnostics for a program without building a separate host harness.

## What `rank test` is for

Use `rank test` when you need:

- repeatable output checks for pure programs
- deterministic fixtures for `Env<T> {}` and `HTTP::Fetch<T> {}`
- local or stubbed provider behavior instead of live backends
- regression coverage for diagnostics as well as success output
- machine-readable suite reports for CI

The command accepts either one case directory or a suite root that contains many case directories:

```sh
rank test examples/tests
rank test examples/tests/yaml-expected
rank test examples/tests --filter provider
rank test examples/tests --format json
```

## Test case layout

Each case directory is driven by a `rank-test.json` manifest.

Minimal value-output case:

```text
my-case/
  rank-test.json
  expected.json
  src/
    main.rank
```

Minimal manifest:

```json
{
  "kind": "rank/test-case",
  "version": 1,
  "entry": "src/main.rank",
  "expectedValue": "expected.json"
}
```

`expectedValue` may point to JSON or YAML. Use JSON when you want the least ambiguity in scalar values and YAML when you want the fixture to read like normal Rank output.

## Output assertions

For ordinary values, the expected file contains the realized document value.

Example expected JSON:

```json
{
  "service": {
    "host": "localhost",
    "port": 443
  }
}
```

If `pub main` returns `Emit::manifest(...)`, the expected value should be the descriptor envelope, not the materialized filesystem tree:

```json
{
  "kind": "rank/output-manifest",
  "version": 1,
  "entries": [
    {
      "path": "README.md",
      "format": "text",
      "value": "# api\n"
    }
  ]
}
```

## Diagnostic assertions

Tests can also pin expected diagnostics instead of an output value.

Example manifest:

```json
{
  "kind": "rank/test-case",
  "version": 1,
  "entry": "src/main.rank",
  "expectedDiagnostics": [
    {
      "code": "TYP007",
      "messageContains": "Field missing does not exist"
    }
  ]
}
```

Use exact `message` only when the full text is intentionally stable. Prefer `messageContains` for diagnostics that include long rendered type shapes or paths.

## Deterministic external inputs

Case directories may include fixture files for external inputs:

- `env.json` for `Env<T> {}` reads
- `http.json` for `HTTP::Fetch<T> {}` snapshots
- `provider-stubs.json` for backend provider outputs keyed by public export name and exact full input
- a local `rank.toml` plus `providers/` directory when you want to exercise a path-based provider package directly

This keeps the suite reproducible even when the production program normally depends on host state or remote services.

### Backend provider stubs

`provider-stubs.json` is a small object keyed by public provider export name:

```json
{
  "api::users::lookup": [
    {
      "input": {
        "id": "123",
        "cacheKey": "lookup-123"
      },
      "output": {
        "name": "stubbed-user-123"
      }
    }
  ]
}
```

Each entry matches the backend provider call by exact full input. If a backend invocation has no matching stub, `rank test` fails instead of falling through to a live runtime call.

## Running suites in CI

Text output is good for local iteration:

```sh
rank test examples/tests
```

Structured reports are better for automation:

```sh
rank test examples/tests --format json
rank test examples/tests --format yaml
```

`--filter <pattern>` is useful when narrowing one failing slice inside a larger suite.

## Where to look next

- The sample cases under [examples/test-fixtures](./examples/test-fixtures.mdx) show several supported workflows.
- The command-line flags are listed in [CLI Reference](./cli.mdx#rank-test--run-lightweight-unit-tests).
- For runtime debugging outside the test harness, see [Debugging](./debugging.mdx).

---

## Debugging


Most Rank debugging falls into three layers:

1. compile-time diagnostics from `rank check`
2. graph and dependency inspection from `rank deps`
3. runtime evaluation tracing from `rank serve --trace-eval` or `rank <entry> --trace-eval-log <path>`

Start with the cheapest layer that can falsify your current hypothesis.

## Compile-time checks first

If the problem is about types, imports, manifest wiring, or provider admission, start with:

```sh
rank check src/main.rank
```

This catches parse, name-resolution, type, manifest, and security-admission problems before any host-side execution starts.

If you are working from the repository source tree via `npm run rank -- ...`, use the same command as a fast compile pass, then confirm external-input examples with `npm run rank -- <entry>` or `npm run rank -- serve <dir>`. The current dev-path `check` command can still report browser-host external-input errors for programs that do work under the packaged CLI or real serve runtime.

## Inspect the dependency graph

When the question is “why does this program need that input or provider?”, use:

```sh
rank deps src/main.rank
rank deps src/main.rank --format json
rank deps src/main.rank --format json --explain <id>
```

This is especially useful for confirming:

- which `Env<T> {}` or `HTTP::Fetch<T> {}` nodes are present
- which provider exports are in play
- where a dependency edge originates in the entry graph

## Request-time server failures

`rank serve` already logs request-time handler diagnostics and unexpected exceptions locally before returning stable HTTP error codes such as `HANDLER_EVALUATION_FAILED`.

For validation-heavy local development, `--dev` also includes more response detail in supported runtime error bodies:

```sh
rank serve . --dev
```

That is useful when the failure is a bad request contract. It is not enough when you need to see the evaluation path that led to a provider call, binding failure, or commit mutation outcome.

## Evaluation trace

Evaluation tracing is opt-in and structured. It emits newline-delimited JSON events with a stable event shape owned by the compiler.

### Bare runs

Use a file sink so stdout still contains only the evaluated result:

```sh
rank src/main.rank --trace-eval-log .rank/eval.ndjson
```

The CLI creates parent directories as needed and truncates the target file at the start of each run.

### Server runs

Use stdout when you want to watch live request handling:

```sh
rank serve . --trace-eval
```

Request-time events inherit request metadata automatically, so concurrent requests can be separated by `executionId` and `requestId`.

### Redaction behavior

The current trace surface is intentionally conservative about values:

- successful trace events carry execution metadata, not full evaluated value payloads
- when a traced failure includes diagnostic notes, values already marked with `@sensitive` stay redacted as `<sensitive>`
- this applies to the same diagnostic renderers used by runtime annotation failures such as `@constraint` and `@unique`

If you need raw sensitive values in trace diagnostics during a trusted local debugging session, opt in explicitly:

```sh
rank src/main.rank --trace-eval-log .rank/eval.ndjson --emit-sensitive
rank serve . --trace-eval --emit-sensitive
```

Outside that opt-in path, trace output keeps sensitive values redacted by default.

## Reading trace events

Each line is one JSON object. Common fields include:

- `schemaVersion`
- `timestamp`
- `executionId`
- `requestId`
- `route`
- `kind`
- `phase`
- `status`
- `sourcePath`
- `modulePath`
- `bindingName`
- `provider`
- `durationMs`
- `message`
- `diagnostic`
- `detail`

Typical event kinds in the current slice:

- `binding.evaluate_started`
- `binding.evaluate_succeeded`
- `binding.evaluate_failed`
- `function.entered`
- `function.exited`
- `function.failed`
- `provider.invoke_started`
- `provider.invoke_succeeded`
- `provider.invoke_failed`
- `commit.mutation_started`
- `commit.mutation_succeeded`
- `commit.mutation_rejected`
- `commit.mutation_unknown`

Example trace line:

```json
{"schemaVersion":1,"timestamp":"2026-05-13T12:04:53.100Z","executionId":"7bb4f25e-8cfd-4d2a-8c60-9c104fabc123","requestId":"7bb4f25e-8cfd-4d2a-8c60-9c104fabc123","route":"root::main::ListTodosRoute","kind":"provider.invoke_failed","phase":"provider","status":"failed","provider":"aws::DynamoDB::Query","message":"Provider aws invocation failed with ConditionalCheckFailedException: The conditional request failed."}
```

## Practical workflows

Show only the high-signal fields from a CLI trace log:

```sh
jq -c '{kind, phase, status, bindingName, provider, route, message}' .rank/eval.ndjson
```

Focus on one live request from `rank serve --trace-eval`:

```sh
rank serve . --trace-eval | jq -c 'select(.requestId == "<request-id>")'
```

Watch commit mutation outcomes only:

```sh
jq -c 'select(.kind | startswith("commit."))' .rank/eval.ndjson
```

## Current scope

The trace surface is intentionally narrow:

- it is for operational debugging, not a step debugger
- it traces semantic execution seams rather than every AST node
- it supplements stable CLI and HTTP outputs rather than replacing them
- it is currently strongest around bindings, functions, providers, and commit mutations

If the question is dependency shape rather than runtime behavior, prefer `rank deps --explain`. If the question is deterministic regression coverage, prefer [Unit Testing](./testing.mdx).

## Related references

- [CLI Reference](./cli.mdx)
- [HTTP Server](./server.mdx)
- [Dependencies](./dependencies.mdx)
- [Language Errors](./language/errors.mdx)

---

## Editor Support


Rank ships a Language Server Protocol (LSP) server and a VS Code extension. Any editor that can spawn a Node process and communicate over stdio can use the server.

## Supported features

| Feature | Description |
|---|---|
| Diagnostics | Type errors and name errors appear as squiggles at the correct source location |
| Hover | Shows the inferred type of any identifier |
| Go-to-definition | Jump to the binding declaration, including across module boundaries |
| Completion | In-scope value names, type names, and language keywords |
| Syntax highlighting | Token-level highlighting for `.rank` files |

## VS Code

### Install

The extension is not yet published to the Marketplace. To install it locally from the repo:

```sh
cd packages/vscode
npm run package           # produces rank-language-support-0.0.1.vsix
code --install-extension rank-language-support-0.0.1.vsix
```

Reload VS Code. Open any `.rank` file — the language ID `rank` is registered automatically and the language server starts in the background.

### How it works

The extension spawns the `@rank-lang/lsp` server as a child process and communicates over stdio. The server calls directly into the Rank compiler pipeline, so diagnostics and type information are always consistent with what `rank check` reports.

## Other LSP editors

The server entry point is `packages/lsp/dist/server.js`. It accepts no flags and communicates over stdio.

**Neovim** (via `nvim-lspconfig`):

```lua
require('lspconfig').configs.rank = {
  default_config = {
    cmd = { 'node', '/path/to/packages/lsp/dist/server.js', '--stdio' },
    filetypes = { 'rank' },
    root_dir = require('lspconfig.util').root_pattern('rank.toml'),
  },
}
require('lspconfig').rank.setup {}
```

**Helix** (`~/.config/helix/languages.toml`):

```toml
[[language]]
name = "rank"
scope = "source.rank"
file-types = ["rank"]
language-servers = ["rank-lsp"]

[language-server.rank-lsp]
command = "node"
args = ["/path/to/packages/lsp/dist/server.js", "--stdio"]
```

**Zed** (`.zed/settings.json`):

```json
{
  "lsp": {
    "rank": {
      "binary": {
        "path": "node",
        "args": ["/path/to/packages/lsp/dist/server.js", "--stdio"]
      }
    }
  }
}
```

## Language ID

The language identifier is `rank`. Use this when configuring file-type associations or LSP settings in editors not listed above.

## Browser editors

Browser-based editors should not embed `@rank-lang/lsp` — it is a Node stdio server and does not run in the browser. Instead, reuse the compiler-side query exports (`hoverInfoAtPosition`, `findDefinitionAtPosition`, `completionItemsAtPosition`) from a browser worker backed by the browser compiler host. See the [Playground](./playground.mdx) page for details on the browser compiler surface.

---

## Faker Provider


Use the Faker provider when you want deterministic test fixtures, seeded datasets, and correlated fake identities without leaving Rank. For runnable examples, start with [Test Fixtures](./examples/test-fixtures.mdx) and [Faker Dataset](./examples/faker-dataset.mdx).

## How providers work

Providers are out-of-process extensions that expose typed functions to Rank programs under a namespace. The compiler spawns the provider process, type-checks calls against the manifest's declared schemas, and exchanges values over a JSON-line stdio protocol.

From a Rank program's point of view, a provider looks like any other import:

```rank
use faker::{ Generate, UUID }
```

The `faker` namespace is backed by the `@rank-lang/plugin-faker` package. Register it in `rank.toml` using the npm registry:

```toml
[providers]
faker = { registry = "npm", package = "@rank-lang/plugin-faker", version = "0.1.0" }
```

On the first run, Rank fetches and caches the package automatically and writes a `rank.lock` file. Subsequent runs reuse the cache. No separate `npm install` step is needed.

The provider is pure — it declares no capabilities — so no `--allow-provider-capability` flag is needed at the call site.

Providers can be distributed through npm the same way as `@rank-lang/plugin-faker`; see the [Provider authoring guide](/docs/provider-authoring) for the publish workflow.

---

## Faker

`@rank-lang/plugin-faker` is a first-party provider package that ships alongside Rank. It is not built into the compiler — it is a separate npm package that must be registered in your project's `rank.toml` like any other provider. Once registered, it exposes its exports through `use faker`.

The provider is deterministic by construction. Every generated value is derived from explicit inputs instead of ambient randomness.

## Exports

| Export | Description |
|---|---|
| `faker::Generate<T>` | Generate one `T` from a typed recipe |
| `faker::UUID {}` | Generate a UUID string |
| `faker::Int { min, max, multipleOf? }` | Generate an integer in a bounded range |
| `faker::Boolean { probability? }` | Generate a boolean with optional weighting |
| `faker::DateTime { ... }` | Generate a `Time::Instant` value |
| `faker::Person { sex? }` | Declare a correlated person scope |
| `faker::Location {}` | Declare a correlated location scope |
| `faker::types::Spec<T>` | Recipe type for composing markers and nested structures |

### `faker::Generate<T>`

The central export. Accepts a `spec` recipe, a `seed`, and optional controls.

## Determinism Controls

`faker::Generate<T>` accepts these core inputs:

- `seed`: required base seed
- `itemKey`: optional deterministic variation input for repeated generation
- `locale`: optional Faker locale such as `en_US`
- `refDate`: required only when relative `faker::DateTime` recipes are used

Reusing the same `(spec, seed, itemKey, locale, refDate)` tuple replays identically.

## Correlated Scopes

`faker::Person` and `faker::Location` are declarative recipe scopes, not sampled runtime objects.

Within one generated item, repeated projections from the same scope stay coherent:

```rank
use faker::{ Generate, Person, UUID }
use faker::types::{ Spec }

User = Object {
  id: string,
  first: string,
  firstAgain: string,
}

person = Person {
  sex: `female`,
}

spec: Spec<User> = {
  id: UUID {},
  first: person.firstName,
  firstAgain: person.firstName,
}

pub main = || Generate<User> {
  spec,
  seed: 123,
  itemKey: 0,
  locale: `en_US`,
}
```

In this example, `first` and `firstAgain` always match within one generated item.

## Repeated Generation

Rank intentionally keeps repeated generation in ordinary collection composition around singular `faker::Generate<T>` calls:

```rank
use faker::{ Generate, UUID }
use faker::types::{ Spec }
use std::collections::{ map }
use std::list::{ range }

User = Object {
  id: string,
}

spec: Spec<User> = {
  id: UUID {},
}

seed = 123

pub main = || range(0, 3)
  |> map(|_, ctx| Generate<User> {
       spec,
       seed,
       itemKey: ctx.index,
       locale: `en_US`,
     })
```

## Validation Behavior

- malformed Faker marker parameters fail during evaluation with provider diagnostics
- unsupported markers nested inside larger specs are rejected during recursive materialization
- generated scalar values participate in ordinary Rank validation flows such as `@unique(group: ...)`

## Deferred Items

The current v1 boundary deliberately excludes a few features:

- probabilistic structural omission helpers inside `faker::Spec<T>`
- collection-scoped uniqueness helpers such as `faker::Unique`
- a broader `faker::DateTime` surface beyond the current bounded and relative forms
- exact structural projection from `T` into the recipe type surface beyond the current recursive `T | SpecValue` compromise

For the implementation plan and remaining deferred work, see the expansion plan in `plan/expansions/FAKER_PLUGIN.md`.

---

## AWS Provider


`@rank-lang/plugin-aws` is a first-party provider package for AWS-backed getters and mutations. It registers the `aws` namespace and ships ordinary Rank source modules alongside provider exports, so you can import typed helpers such as `DynamoDB::createClient` and `DynamoDB::Table<...>` directly from the provider package.

Like other providers, it is not built into the compiler. Register it in your project's manifest and Rank will materialize it through the same cache and lockfile flow used for registry-backed dependencies.

Start here if you want typed AWS reads and explicit write plans from Rank. For runnable setups, see [Secrets-Backed Config](./examples/secrets-backed-config.mdx), [LocalStack Bootstrap](./examples/localstack-bootstrap.mdx), [DynamoDB Report](./examples/dynamodb-report.mdx), and [S3 Logs](./examples/s3-logs.mdx).

## Install

Register the package in `rank.toml`:

```toml
manifestVersion = 1

[package]
name = "aws-example"
version = "0.1.0"
source = "src"

[providers]
aws = { registry = "npm", package = "@rank-lang/plugin-aws", version = "0.1.0" }
```

The package exposes three public modules:

```rank
use aws::{ DynamoDB, S3, SecretsManager }
```

For provider registration rules, registry configuration, and host security defaults, see the [manifest reference](/docs/manifest-reference).

## Current Surface

`@rank-lang/plugin-aws` currently provides:

- `DynamoDB::Item` and `DynamoDB::Query` getters
- `S3::Object<T>` and `SecretsManager::Secret<T>` getters
- `DynamoDB::Put`, `DynamoDB::Update`, and `S3::Put` mutation exports
- provider-owned Rank modules for `aws::DynamoDB`, `aws::S3`, and `aws::SecretsManager`
- typed helper aliases such as `Table<T, PK>`, `UpdatePatch`, and `createClient(...)`

The provider runtime memoizes live AWS SDK clients per provider session. The `createClient(...)` helpers themselves return plain serializable config objects, so they remain safe to use in pure preparation and serve-time setup flows.

## Quick Start

Create typed client configs in ordinary Rank code:

```rank
use aws::{ DynamoDB, S3, SecretsManager }

dynamoClient: aws::DynamoDB::ClientConfig = DynamoDB::createClient({
  region: `us-east-1`,
})

s3Client: aws::S3::ClientConfig = S3::createClient({
  region: `us-east-1`,
})

secretsClient: aws::SecretsManager::ClientConfig = SecretsManager::createClient({
  region: `us-east-1`,
})
```

These values are serializable configs, not live SDK clients. The live client instances exist only inside the admitted provider runtime.

## Getter Example

```rank
use aws::{ DynamoDB, S3, SecretsManager }

User = Object {
  userId: string,
  email: string,
  status: `active` | `inactive`,
}

UsersTable = DynamoDB::Table<User, `userId`>

dynamoClient: aws::DynamoDB::ClientConfig = DynamoDB::createClient({
  region: `us-east-1`,
})

{ item, metadata } = DynamoDB::Item<UsersTable> {
  client: dynamoClient,
  tableName: `Users`,
  key: {
    userId: `123`,
  },
}
```

Additional getter notes:

- `DynamoDB::Query<Resource>` uses explicit `target` metadata and narrows `indexName` based on the selected table or index resource.
- `S3::Object<T>` reads UTF-8 JSON objects.
- `SecretsManager::Secret<T>` currently supports `format: string` and `format: json`.

## Declaring Effects

```rank
use aws::DynamoDB::{ Table, UpdatePatch }
use std::Mutation

User = Object {
  userId: string,
  email: string,
  status: `active` | `inactive`,
}

UsersTable = Table<User, `userId`>
UserPatch = UpdatePatch<UsersTable>

dynamoClient: aws::DynamoDB::ClientConfig = aws::DynamoDB::createClient({
  region: `us-east-1`,
})

s3Client: aws::S3::ClientConfig = aws::S3::createClient({
  region: `us-east-1`,
})

putUser: Mutation::Effect<User> = aws::DynamoDB::Put<UsersTable> {
  client: dynamoClient,
  tableName: `Users`,
}

activateUser: Mutation::Effect<UserPatch> = aws::DynamoDB::Update<UsersTable, UserPatch> {
  client: dynamoClient,
  tableName: `Users`,
  key: {
    userId: `123`,
  },
}

uploadUser: Mutation::Effect<User> = aws::S3::Put<User> {
  client: s3Client,
  bucket: `profiles`,
  key: `users/123.json`,
}

created = putUser({
  userId: `123`,
  email: `alice@example.com`,
  status: `inactive`,
})

activated = activateUser({
  status: `active`,
})

uploaded = uploadUser({
  userId: created.userId,
  email: created.email,
  status: created.status,
})
```

Fulfillment returns the declared payload value rather than the provider receipt. Receipt metadata is still retained for commit summaries and `Mutation::commit(...)` projections.

## Complete Project Example

The earlier snippet shows how AWS-backed effects are declared and fulfilled, but it still does not commit anything by itself. A complete runnable project also needs:

- provider registration in `rank.toml`
- host admission for `network` plus the exact mutation export names you call
- a top-level `pub main` that returns `Mutation::commit(...)`

`rank.toml`:

```toml
manifestVersion = 1

[package]
name = "aws-mutation-example"
version = "0.1.0"
source = "src"

[providers]
aws = { registry = "npm", package = "@rank-lang/plugin-aws", version = "0.1.0" }

[security]
allow-provider-capabilities = ["network"]
allow-provider-mutation-exports = [
  "aws::DynamoDB::Put",
]
```

`src/main.rank`:

```rank
use aws::DynamoDB::{ Table }
use std::Mutation

User = Object {
  userId: string,
  email: string,
  status: `active` | `inactive`,
}

UsersTable = Table<User, `userId`>

dynamoClient: aws::DynamoDB::ClientConfig = aws::DynamoDB::createClient({
  region: `us-east-1`,
})

putUser: Mutation::Effect<User> = aws::DynamoDB::Put<UsersTable> {
  client: dynamoClient,
  tableName: `Users`,
}

plan = Mutation::plan({
  created: putUser({
    userId: `123`,
    email: `alice@example.com`,
    status: `active`,
  }),
})

pub main = ||
  Mutation::commit(
    plan,
    |report| {
      status: report.status,
      created: report.operations.created,
    },
  )
```

This example is structurally complete. To run it against real AWS or LocalStack, the target `Users` table must exist and the credentials or explicit endpoints passed to `createClient(...)` must be valid for that environment.

Running `rank src/main.rank` now evaluates the program, commits the plan, and prints the projected commit result as YAML by default. Pass `--format json` if you want JSON instead. `rank check` still only type-checks the graph and does not perform the write.

## Commit Timing

Provider mutators are intentionally explicit about when I/O happens:

- declaring `putUser: Mutation::Effect<User>` is static
- calling `putUser({...})` fulfills the payload and returns a commit-local `User` value
- `Mutation::plan(...)` stays pure and only records required operations
- the actual AWS write happens only when a host realizes the top-level `Mutation::commit(...)` descriptor

That explicit commit boundary is what lets Rank keep ordinary evaluation deterministic while still making writes typed, host-admitted, and projectable into ordinary output.

For the language-level mutation flow, see [Mutations](./language/mutations.mdx).

## Emit And Serve

The same top-level `Mutation::commit(...)` descriptor can also be returned from `HTTP::Response.body`. That means AWS mutation outcomes can flow into CLI output, manifest emission, or serve responses without manually unpacking provider receipts.

```rank
use std::HTTP
use std::Mutation
use std::Runtime
use aws::DynamoDB::{ Table, createClient }

HealthRoute = HTTP::Route {
  method: `GET`,
  path: `/health`
}

Routes = HealthRoute

Entry = Object {
  id: string,
  active: bool,
}

UsersTable = Table<Entry, `id`>

dynamoClient: aws::DynamoDB::ClientConfig = createClient({
  region: `us-east-1`,
})

putUser: Mutation::Effect<Entry> = aws::DynamoDB::Put<UsersTable> {
  client: dynamoClient,
  tableName: `Users`,
}

pub main = |req: Runtime::ExecutionContext<Routes>| {
  status: 200,
  body: Mutation::commit(
    Mutation::plan({
      createdUser: putUser({ id: `1`, active: true })
    }),
    |report| {
      commitStatus: report.status,
      createdUser: report.operations.createdUser,
    }
  )
}
```

For more on output shapes, see [Output and manifests](/docs/language/output). For serve-specific runtime behavior, see [Server](/docs/server).

## Security And Operations

This provider is intentionally explicit about host admission:

- getter and mutation exports require the `network` provider capability
- mutation exports are separately default-denied and must be explicitly allowlisted by exact name
- the host does not currently add AWS-specific table, bucket, or secret allowlists on top of IAM

Typical host security config:

```toml
[security]
allow-provider-capabilities = ["network"]
allow-provider-mutation-exports = [
  "aws::DynamoDB::Put",
  "aws::DynamoDB::Update",
  "aws::S3::Put",
]
```

IAM remains the real resource boundary. Use least-privilege policies for the tables, buckets, and secrets your program touches.

If credentials enter through `Env<T>`, destructure them through `@sensitive` bindings so they stay redacted in diagnostics:

```rank
use std::Env

SysEnvironment = Object {
  AWS_ACCESS_KEY_ID: string,
  AWS_SECRET_ACCESS_KEY: string,
  ...: string,
}

@sensitive
{ AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY } = Env<SysEnvironment> {}
```

## Typed Helpers

The provider-owned source modules expose additional schema helpers beyond the runtime exports.

### DynamoDB

- `Table<T, PK, SK?>` declares a base table schema
- `GSI<BaseTable, Name, IndexTable>` and `LSI<BaseTable, Name, IndexTable>` declare query-only secondary-index schemas
- `KeyInput` derives the exact key object from the table schema
- `UpdatePatch` is shallow and excludes declared key fields
- `QueryInput<Resource>` specializes table, GSI, and LSI query inputs

### Receipts And Metadata

- getter results return request metadata structures
- `DynamoDB::PutReceipt` and `DynamoDB::UpdateReceipt` include `requestId` and optional consumed-capacity summaries
- `S3::PutReceipt` includes `requestId` and optional `eTag` / `versionId`

## LocalStack And Development

The package keeps a pinned LocalStack harness in `packages/plugins/aws/test/localstack/docker-compose.yml` for DynamoDB, S3, and Secrets Manager.

Typical workflow from the repo root:

```sh
npm run localstack:up -w @rank-lang/plugin-aws
npm run test:localstack -w @rank-lang/plugin-aws
npm run localstack:down -w @rank-lang/plugin-aws
```

General package development commands:

```sh
npm run build -w @rank-lang/plugin-aws
npm run typecheck -w @rank-lang/plugin-aws
npm run test -w @rank-lang/plugin-aws
```

## Known v1 Limitations

- `S3::Object<T>` and `S3::Put<T>` are JSON-only in v1
- `SecretsManager::Secret<T>` supports `SecretString` only; `SecretBinary` is rejected
- `DynamoDB::Update` currently lowers shallow `SET` updates only
- `DynamoDB::Query<Resource>` uses native DynamoDB expression strings rather than a typed DSL
- resource-scoped host allowlists for AWS tables, buckets, and secrets are still deferred

For provider packaging and publication workflows, see the [provider authoring guide](/docs/provider-authoring).

---

## Dependencies


Rank dependencies are reusable packages of pure `.rank` modules. Declare them in `[dependencies]`, then import them under the alias you chose in `rank.toml`.

A dependency is not a provider. Dependencies do not declare `[provider]`, do not have a host runtime entrypoint, and do not request provider capabilities. Use a dependency for shared types, helper functions, transforms, and schemas. Use a provider when the package needs host-side behavior.

Dependencies can be loaded from:

- a local path
- an npm-compatible registry package
- a git repository snapshot

## Local dependencies

Local dependencies are the simplest way to share Rank modules across nearby projects.

```toml
[dependencies]
shared = { path = "./vendor/shared" }
```

```rank
use shared::types::{ AppConfig }
use shared::render::{ render_config }
```

The dependency root needs a normal `rank.toml` with a `[package]` table and a `source` directory.

## Publish to npm

Registry-backed dependencies are ordinary npm packages that include Rank source files.

Minimal package layout:

```text
rank-shared/
  rank.toml
  package.json
  src/
    index.rank
    types.rank
```

`rank.toml`:

```toml
manifestVersion = 1

[package]
name = "@acme/rank-shared"
version = "0.1.0"
source = "src"
```

`package.json`:

```json
{
  "name": "@acme/rank-shared",
  "version": "0.1.0",
  "files": [
    "rank.toml",
    "src"
  ],
  "publishConfig": {
    "access": "public"
  }
}
```

Before publishing:

1. Keep the package name and version aligned across `rank.toml` and `package.json`.
2. Make sure the published tarball includes `rank.toml` and every `.rank` file under `[package].source`.
3. If you publish a scoped package to the public npm registry, set `publishConfig.access = "public"`.
4. Run `npm pack --dry-run`, then publish with `npm publish`.

Consumers can then install the dependency directly from the registry in `rank.toml`:

```toml
[dependencies]
shared = { registry = "npm", package = "@acme/rank-shared", version = "0.1.0" }
```

If `registry` is omitted, Rank uses the default registry or a matching `[registryScopes]` rule.

## Publish via git

There is no separate Rank-specific git publish command. Publishing via git means pushing a repository that contains a normal Rank package, then referencing that repository from `[dependencies]`.

Tag-based reference:

```toml
[dependencies]
shared = { git = "https://github.com/acme/rank-shared.git", tag = "v0.1.0" }
```

Commit-pinned reference:

```toml
[dependencies]
shared = { git = "https://github.com/acme/rank-shared.git", rev = "8d91b7c4e5d0c1a2b3f4e5d6c7b8a9b0c1d2e3f4" }
```

Monorepo package in a subdirectory:

```toml
[dependencies]
ui = { git = "ssh://git@github.com/acme/mono.git", rev = "6a1f0d9a8b7c6e5d4c3b2a190817161514131211", subdir = "packages/rank-ui" }
```

Use `tag` when you want a release workflow with named versions. Use `rev` when you want an exact immutable commit pin from the start. In both cases, the referenced repository still needs a normal `rank.toml` and `[package]` table at the package root.

Git-backed references are currently for `[dependencies]` only. Providers are path- or registry-backed, not git-backed.

## Locking and caching

Rank materializes registry packages and git snapshots on first use, or explicitly through `rank sync .`, and writes the result to `rank.lock`.

- registry-backed dependencies lock to a concrete tarball and integrity hash
- `{ git, tag }` dependencies lock the requested tag plus the resolved commit
- `{ git, rev }` dependencies lock the requested and resolved commit

Commit `rank.lock` alongside `rank.toml`. That is what makes `--offline` and `--frozen-lockfile` reproducible in CI and deploy builds.

See also:

- [Manifest Reference](./manifest-reference.mdx)
- [CLI Reference](./cli.mdx)
- [Provider authoring](/docs/provider-authoring)

---

## Provider authoring


A Rank provider is an out-of-process Node.js program that exposes typed functions to Rank programs under a namespace. The compiler spawns the provider process, negotiates a protocol handshake, and sends typed invocation requests over stdin/stdout.

Use this guide when you want to publish your own provider package. For concrete shipped examples, compare the pure [Faker Provider](./faker-provider.mdx) with the capability-bearing [AWS Provider](./aws-provider.mdx), and keep the [Manifest Reference](./manifest-reference.mdx) nearby for provider registration rules.

This guide walks through creating a minimal provider from scratch. The `@rank-lang/plugin-faker` package (`packages/plugins/faker/`) is the canonical reference implementation.

## Overview

A provider consists of:

1. A directory containing a `rank.toml` manifest with `[provider]` metadata
2. A Node.js entry point that implements the stdio protocol
3. Optionally, `.rank` source files that expose types and helper bindings to Rank programs

The consuming project registers the provider in its own `rank.toml` under `[providers]`.

## Step 1: Create the provider directory

```sh
mkdir -p providers/greeter/src
cd providers/greeter
```

## Step 2: Write the manifest

`providers/greeter/rank.toml`:

```toml
manifestVersion = 1

[package]
name = "greeter-provider"
version = "0.1.0"
source = "src"

[provider]
namespace = "greeter"
runtime = "node"
entry = "./src/provider.js"

[[provider.exports]]
name = "Greet"
kind = "function"
inputSchema = "types::GreetInput"
outputSchema = "types::Greeting"
capabilities = []
```

Key fields:

| Field | Description |
|---|---|
| `namespace` | The name Rank programs use to import from this provider (`use greeter::...`) |
| `runtime` | Must be `node` |
| `entry` | Path to the Node.js entry point, relative to the manifest |
| `[[provider.exports]]` | One block per exported function |

Each export block:

| Field | Description |
|---|---|
| `name` | The exported function name, used in `use greeter::{ Greet }` |
| `kind` | Always `function` for v0 |
| `inputSchema` | Type expression for the input value. References types from the provider's source modules |
| `outputSchema` | Type expression for the return value |
| `capabilities` | Declared capabilities. Use `["network"]` if the provider makes network requests. Use `[]` for pure providers |

## Step 3: Define the type schemas

`providers/greeter/src/types.rank`:

```rank
pub GreetInput = Object {
  name: string,
  formal?: bool,
}

pub Greeting = Object {
  message: string,
  name: string,
}
```

Type files are ordinary Rank source modules. They are loaded by the compiler (not the provider process) and used for type-checking the call sites.

## Step 4: Implement the provider process

Add `@rank-lang/provider-runtime` as a dependency in your provider's `package.json`. This package provides `runNodeProviderLoop`, which handles the JSON-lines stdio protocol so you only need to implement your domain logic.

`providers/greeter/package.json`:

```json
{
  "name": "greeter-provider",
  "version": "0.1.0",
  "type": "module",
  "dependencies": {
    "@rank-lang/provider-runtime": "^0.1.0"
  }
}
```

`providers/greeter/src/provider.js`:

```js
import { pathToFileURL } from "node:url";
import { runNodeProviderLoop } from "@rank-lang/provider-runtime";

const NAMESPACE = "greeter";

async function invoke(exportName, input) {
  switch (exportName) {
    case "Greet": {
      const { name, formal } = input;
      const prefix = formal ? "Good day" : "Hello";
      return {
        ok: true,
        output: {
          message: `${prefix}, ${name}!`,
          name,
        },
      };
    }
    default:
      return {
        ok: false,
        code: "UnknownExport",
        message: `Unknown export: ${exportName}`,
      };
  }
}

const invokedPath = process.argv[1];
if (invokedPath && import.meta.url === pathToFileURL(invokedPath).href) {
  runNodeProviderLoop({ namespace: NAMESPACE, invoke }).catch((err) => {
    process.stderr.write(`greeter provider crashed: ${err.message}\n`);
    process.exitCode = 1;
  });
}
```

`runNodeProviderLoop` owns the protocol handshake, version negotiation, request routing, and shutdown. Your `invoke(exportName, input)` function returns either `{ ok: true, output }` or `{ ok: false, code, message }`. See the [stdio protocol section](#the-stdio-protocol) below for what the runtime is handling on your behalf.

## The stdio protocol

The compiler communicates with the provider process over newline-delimited JSON on stdin/stdout. All messages are single-line JSON objects terminated by `\n`.

### Handshake

The compiler sends:

```json
{ "message": "initialize", "protocolVersion": 1, "namespace": "greeter" }
```

The provider must respond with a success result before any invocations are sent:

```json
{ "message": "initializeResult", "protocolVersion": 1, "namespace": "greeter", "ok": true }
```

On failure:

```json
{ "message": "initializeResult", "protocolVersion": 1, "namespace": "greeter", "ok": false,
  "error": { "code": "UnsupportedProtocolVersion", "message": "..." } }
```

### Invocation

```json
{ "message": "invoke", "requestId": "req-1", "export": "Greet", "input": { "name": "Alice" } }
```

Success response:

```json
{ "message": "invokeResult", "requestId": "req-1", "ok": true, "output": { "message": "Hello, Alice!", "name": "Alice" } }
```

Error response:

```json
{ "message": "invokeResult", "requestId": "req-1", "ok": false,
  "error": { "code": "InvalidInput", "message": "name is required" } }
```

### Shutdown

```json
{ "message": "shutdown" }
```

The provider should exit cleanly when it receives `shutdown`. No response is required.

### Rules

- All values exchanged are ordinary Rank-compatible data: strings, numbers, booleans, `null`, lists, and plain objects
- `requestId` is a string chosen by the compiler. Echo it back in `invokeResult`
- The provider must not write anything to stdout before receiving `initialize`
- Stderr is available for diagnostic output and does not affect the protocol

## Step 5: Register the provider in the project

In the consuming project's `rank.toml`, add a `[providers]` table that maps the namespace alias to the provider.

For a local provider directory:

```toml
[providers]
greeter = { path = "./providers/greeter" }
```

For a published npm package:

```toml
[providers]
greeter = { registry = "npm", package = "greeter-provider", version = "0.1.0" }
```

With a registry-backed reference, Rank fetches and caches the package on first run and writes a `rank.lock` file. Subsequent runs reuse the cache without network access.

The alias key must match the `namespace` field in the provider's `rank.toml`.

## Step 6: Use the provider in Rank code

```rank
use greeter::{ Greet }

pub main = || Greet {
  name: `Alice`,
  formal: true,
}
```

Run:

```sh
rank src/main.rank
```

```yaml
message: Good day, Alice!
name: Alice
```

## Step 7: Validate

```sh
rank check src/main.rank
```

The compiler type-checks the call site against the schemas declared in the provider manifest. If `GreetInput` or `Greeting` do not match the actual input/output values, you will get a type error.

## Publish to npm

Providers are ordinary npm packages. Publishing one is mostly standard npm packaging, with one Rank-specific requirement: the published tarball must include the provider's `rank.toml`, the Node.js entrypoint declared by `[provider].entry`, and any `.rank` source modules referenced from `[package].source`.

Before publishing:

1. Keep the package name and version aligned across `rank.toml` and `package.json`.
2. Make sure the published files include `rank.toml`, your built JS files, and any shipped `.rank` modules.
3. If you publish a scoped package to the public npm registry, set `publishConfig.access = "public"`.
4. Run `npm pack --dry-run` to confirm the tarball contents before `npm publish`.

Example `package.json` additions:

```json
{
  "name": "@acme/greeter-provider",
  "version": "0.1.0",
  "type": "module",
  "files": [
    "dist",
    "src",
    "rank.toml"
  ],
  "publishConfig": {
    "access": "public"
  },
  "dependencies": {
    "@rank-lang/provider-runtime": "^0.1.0"
  }
}
```

Consumers can then install the provider directly from npm through `rank.toml`:

```toml
[providers]
greeter = { registry = "npm", package = "@acme/greeter-provider", version = "0.1.0" }
```

On the consuming side, no separate `npm install` step is required. Rank fetches the provider package, caches it locally, and records it in `rank.lock`. Providers are registry- or path-backed in this slice; git-backed references are for `[dependencies]`, not `[providers]`.

## Provider capabilities

If your provider makes network requests, declare the capability in the manifest:

```toml
[[provider.exports]]
name = "Fetch"
kind = "function"
inputSchema = "types::FetchInput"
outputSchema = "types::FetchOutput"
capabilities = ["network"]
```

At the call site, pass `--allow-provider-capability network`:

```sh
rank src/main.rank --allow-provider-capability network
```

Without this flag, the compiler blocks execution and reports a capability error. This makes capability use explicit and auditable in CI pipelines.

## Generic export clauses

Host exports can declare generic parameter clauses in `rank.toml` using the same syntax as source type aliases:

```toml
[[provider.exports]]
name = "Lookup"
kind = "function"
typeParameters = ["T", "K extends keyof T = `id`"]
inputSchema = "types::LookupInput<T, K>"
outputSchema = "T[K]"
capabilities = []
```

Keep one clause per string entry. Later clauses may reference earlier parameters in bounds and defaults, and defaulted clauses must remain a trailing suffix.

## Reference implementation

`packages/plugins/faker/` is the canonical first-party provider. Study it for:

- `rank.toml` with multiple exports, generic type parameters, and `typeParameters`
- `src/types.rank` with complex input/output schemas
- `src/provider.js` using `runNodeProviderLoop` from `@rank-lang/provider-runtime` for protocol handling
- `src/runtime.js` for separating domain logic from protocol mechanics

## `@rank-lang/provider-runtime`

`@rank-lang/provider-runtime` is the shared JS helper package for Rank provider authors. Declare it as a runtime `dependency` in your provider's `package.json`.

Main exports:

| Export | Description |
|---|---|
| `runNodeProviderLoop({ namespace, invoke })` | Runs the full JSON-lines stdio protocol loop. Calls `invoke(exportName, input)` per request. |
| `PROVIDER_PROTOCOL_VERSION` | The current protocol version integer. |
| `initializeResult(namespace, error?)` | Builds an `initializeResult` message. Useful for advanced protocol customization. |
| `invokeSuccess(requestId, output)` | Builds a successful `invokeResult` message. |
| `invokeError(requestId, code, message)` | Builds an error `invokeResult` message. |

RNG utilities (from `@rank-lang/provider-runtime/rand`):

| Export | Description |
|---|---|
| `stdlibRandSeedState(seed)` | Seed an RNG state from an integer. |
| `stdlibRandDeriveState(state, label)` | Derive a child RNG state from a label. |
| `stdlibRandNextUnitFloat(state)` | Draw the next float in `[0, 1)`. |
| `stdlibRandNextInt(state, min, max)` | Draw the next integer in `[min, max]` (BigInt bounds). |
| `stdlibRandChooseIndex(state, length)` | Draw a random array index. |

---

## Project Structure


The repository is a TypeScript monorepo. Source-of-truth documents live alongside the code so implementation decisions and language spec stay in sync.

## Top-level layout

```
packages/         workspace packages (compiler, CLI, server runtime, plugins)
spec/             modular language specification chapters
plan/             implementation plan, architecture, roadmap, and testing notes
testdata/         shared fixtures used by the CLI integration suite
integration/      cross-package smoke tests run against built artifacts
website/          this Docusaurus documentation site
```

## Workspace packages

| Package | Name | Description |
|---|---|---|
| `packages/compiler` | `@rank-lang/compiler` | Compiler library and programmatic API: parsing, resolution, type checking, evaluation, emission, providers |
| `packages/cli` | `rank` | The `rank` CLI binary |
| `packages/server-runtime` | `@rank-lang/server-runtime` | Serve-time runtime boundary for `rank serve` |
| `packages/plugins/faker` | `@rank-lang/plugin-faker` | First-party Faker provider |

Dependency direction: `rank → @rank-lang/compiler`, `rank → @rank-lang/server-runtime`, `@rank-lang/server-runtime → @rank-lang/compiler`.

## Compiler areas

Inside `packages/compiler/src/`:

| Directory | Responsibility |
|---|---|
| `parser/` | Lexing and parsing; produces the AST |
| `names/` | Import resolution and name binding |
| `types/` | Static type checking |
| `eval/` | Deterministic graph evaluation and provider runtime interaction |
| `modules/` | Project graph loading and manifest handling |
| `emit/` | JSON, YAML, and TOML output serialization |
| `annotations/` | Compile-time annotation and constraint evaluation |
| `providers/` | Provider process protocol and lifecycle |
| `diagnostics/` | Diagnostic formatting and rendering |

## Fixture corpus

`packages/compiler/testdata/` contains parser and type-checking fixtures scoped to the compiler package.

`testdata/` at the repository root contains shared fixtures still used by the CLI integration suite — manifests, source programs, and module-level scenarios.

## Source documents

The spec and plan are kept close to the code so implementation work can update language decisions and compiler behavior in the same commit.

- `spec/` — modular language specification; `SPEC.md` is the index
- `plan/` — implementation plan and roadmap; `PLAN.md` is the index
- `plan/roadmap/` — one file per completed or planned phase

This docs site is the guided front door. The source documents remain authoritative for language semantics and compiler internals.

---

## Spec And Plan


The docs site is the reader-friendly entry point, but the current source documents for the project still live in the repository root and remain authoritative.

## Specification

The language specification is indexed from `SPEC.md` and split across the `spec/` directory.

Recommended starting points:

- `spec/00-status.md`
- `spec/01-overview.md`
- `spec/05-type-model.md`
- `spec/06-syntax-draft.md`
- `spec/12-external-services-and-fetch-nodes.md`

## Plan

The implementation plan is indexed from `PLAN.md` and split across the `plan/` directory.

Recommended starting points:

- `plan/overview.md`
- `plan/architecture.md`
- `plan/roadmap.md`
- `plan/testing.md`

## Current State

- the spec is modularized and serves as the source of truth
- the bootstrap compiler is implemented in TypeScript
- the current implementation plan tracks Phases 0 through 5 as complete
- the docs site is being introduced now as the initial long-term documentation surface

## Practical Reading Order

For language shape:

1. `SPEC.md`
2. `spec/00-status.md`
3. `spec/01-overview.md`
4. `spec/05-type-model.md`
5. `spec/06-syntax-draft.md`

For compiler implementation direction:

1. `PLAN.md`
2. `plan/overview.md`
3. `plan/architecture.md`
4. `plan/roadmap.md`