> ## Documentation Index
> Fetch the complete documentation index at: https://forst-lang.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Roadmap

> What exists, what is in flight, and what Forst deliberately omits.

Forst is under active development. This page is a **simplified** view. The canonical parity tables, RFC links, and implementation notes live in [ROADMAP.md on GitHub](https://github.com/forst-lang/forst/blob/main/ROADMAP.md).

## Status icons

|                                                                           | Status           | Meaning                                          |
| ------------------------------------------------------------------------- | ---------------- | ------------------------------------------------ |
| <Icon icon="circle-check" iconType="solid" size={16} color="#16A34A" />   | **Done**         | Complete for current scope. Report gaps as bugs. |
| <Icon icon="hourglass-half" iconType="solid" size={16} color="#CA8A04" /> | **In progress**  | Actively being implemented toward the done bar.  |
| <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" />          | **Experimental** | Exists in some form; not at the done bar yet.    |
| <Icon icon="calendar" iconType="solid" size={16} color="#64748B" />       | **Planned**      | On the roadmap; not delivered yet.               |
| <Icon icon="ban" iconType="solid" size={16} color="#DC2626" />            | **Omitted**      | Deliberately excluded from the language design.  |

## Language and types

| Status                                                                  | Feature                                                            | Notes                                                                                                                                                                                                    |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" />        | [Shapes and constraints](/docs/language/shapes-and-constraints)         | Structural types and built-in constraints; compile-time checks where values are static, runtime validation via `ensure` in the body today. Parameter prologue emission is future work.                   |
| <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" />        | [`ensure`, `is`, and shape guards](/docs/language/ensure-and-narrowing) | Runtime checks tied to types; shape refinement on records. Successor narrowing after `ensure` works for simple identifiers; compound paths still open.                                                   |
| <Icon icon="circle-check" iconType="solid" size={16} color="#16A34A" /> | [Nil and presence checks](/docs/language/ensure-and-narrowing)          | `ensure x is Nil()`, `ensure !x`, and `*T` `.Present()` / `.Nil()` on pointers. Not full optional value types yet.                                                                                       |
| <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" />        | [Type guards](/docs/language/type-guards)                               | Domain predicates with `is (subject T) Name { … }`; narrowing polish still open.                                                                                                                         |
| <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" />        | [Result and nominal errors](/docs/language/errors-and-result)           | `Result(S, F)`, `error X { … }`, and `ensure` / `if x is Ok()` narrowing. Closed nominal error unions (`ParseError \| IoError`) emit sealed Go interfaces. Failure-type and export rules still maturing. |
| <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" />        | Control-flow narrowing                                             | If-branch refinement works; ensure-successor narrowing for simple identifiers works; compound paths and join across branches still open.                                                                 |
| <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" />        | Type aliases                                                       | Simple `type Name = BaseType` works end-to-end; broader alias semantics still evolving.                                                                                                                  |
| <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" />        | Binary types (`A \| B`, `A & B`)                                   | Union and intersection typedefs type-check; closed nominal error unions emit to Go and TS. General unions, intersections, and narrowing still incomplete.                                                |
| <Icon icon="calendar" iconType="solid" size={16} color="#64748B" />     | Optional types (`T \| Nil`)                                        | Planned: Crystal-style `T \| Nil` / `T?` unions, narrowing, and Go lowering. See [optionals RFC](https://github.com/forst-lang/forst/tree/main/examples/in/rfc/optionals).                               |
| <Icon icon="calendar" iconType="solid" size={16} color="#64748B" />     | User-defined generics                                              | Type parameters on types and functions.                                                                                                                                                                  |
| <Icon icon="circle-check" iconType="solid" size={16} color="#16A34A" /> | Postfix `++` / `--` and compound assignment                        | `+=`, `-=`, `*=`, `/=`, `%=`, `&=`, `\|=` as standalone statements and in `for` post clauses (`lang_probe/59_inc_compound`).                                                                             |
| <Icon icon="calendar" iconType="solid" size={16} color="#64748B" />     | Shift / xor compound assignment                                    | `^=`, `<<=`, `>>=`, `&^=`—planned when `^`, `<<`, `>>`, and `&^` tokens and three-character lexing land.                                                                                                 |
| <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" />        | Slice subslice expressions                                         | `xs[low:high]`, `xs[low:]`, `xs[:high]` on Forst `[]T` values. Example: `examples/in/slices.ft` (`task example:slices`).                                                                                 |
| <Icon icon="calendar" iconType="solid" size={16} color="#64748B" />     | `switch` / `select`                                                | Not implemented yet; design open for Go-style `switch` vs pattern `match`.                                                                                                                               |

## Go interoperability

| Status                                                                  | Feature                                                                        | Notes                                                                                                                                                                                      |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <Icon icon="circle-check" iconType="solid" size={16} color="#16A34A" /> | [Transpile to Go](/docs/interop/go)                                                 | Packages, types, and functions emit as readable Go for `go build`.                                                                                                                         |
| <Icon icon="circle-check" iconType="solid" size={16} color="#16A34A" /> | [Validation from constraints](/docs/language/shapes-and-constraints)                | Compiler emits runtime checks from type constraints.                                                                                                                                       |
| <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" />        | [Providers (`use` / `with`)](/docs/language/providers)                              | Transitive obligation chains, Go lowering, and cross-package fixed-point (emit-time shims, no committed Go stubs). RFC GA gaps (LSP polish, discovery JSON, sidecar host patterns) remain. |
| <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" />        | [Import and type-check Go packages](/docs/interop/go)                               | `go/packages` loading and Forst↔Go call checking; common paths work, not full parity. Forst sibling imports in the same module resolve from `.ft` sources (not committed Go stubs).        |
| <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" />        | [Variadic spread into Go calls](/docs/interop/go#variadic-spread-into-go-calls)     | `argv[1:]...` at Go call sites. Example: `examples/in/go_interop/cli.ft` (`task example:go-interop`).                                                                                      |
| <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" />        | [Fields and methods on Go values](/docs/interop/go#fields-and-methods-on-go-values) | Dotted chains on Go-typed bindings (e.g. `cmd.ProcessState.ExitCode()`).                                                                                                                   |
| <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" />        | [Mixed `.ft` and `.go` modules](/docs/interop/go)                                   | Adopt beside hand-written Go in one module tree.                                                                                                                                           |
| <Icon icon="calendar" iconType="solid" size={16} color="#64748B" />     | Selectable Go emit target version                                              | Emit for older `go` toolchains than the compiler uses today.                                                                                                                               |

## Node interoperability

| Status                                                                  | Feature                                                            | Notes                                                                                                        |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| <Icon icon="circle-check" iconType="solid" size={16} color="#16A34A" /> | [`forst generate` (`.d.ts`)](/docs/interop/node/generate-types)         | Merged TypeScript declarations from `.ft` sources; shared `ftconfig` discovery with `forst dev`.             |
| <Icon icon="circle-check" iconType="solid" size={16} color="#16A34A" /> | [Provider-free client surface](/docs/interop/node/generate-types)       | TS emit and sidecar wire stay data-only; functions with unsatisfied `Providers(f)` are omitted from exports. |
| <Icon icon="circle-check" iconType="solid" size={16} color="#16A34A" /> | [`forst dev` HTTP API](/docs/workflow/dev-server)                       | `/health`, `/functions`, `/invoke`, `/types`, `/version` for local iteration.                                |
| <Icon icon="circle-check" iconType="solid" size={16} color="#16A34A" /> | [Sidecar invoke contract](/docs/interop/node/call-forst)                | Stable JSON `POST /invoke` from Node clients to a running dev server.                                        |
| <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" />        | [Built-in HTTP server + `@forst/client`](/docs/interop/node/call-forst) | In-process `/invoke` in compiled Go binaries; generated flat exports. Pin in production.                     |
| <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" />        | [`@forst/sidecar` and `@forst/cli`](/docs/installation)                 | npm/JSR packages; watch reload, optional debounced `forst generate`, and version checks. Pin in production.  |
| <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" />        | [Client helper stubs](/docs/interop/node/generate-types)                | Thin generated helpers next to `types.d.ts`.                                                                 |
| <Icon icon="calendar" iconType="solid" size={16} color="#64748B" />     | Protobuf sidecar wire                                              | gRPC / Connect as a future high-throughput alternative to JSON.                                              |
| <Icon icon="calendar" iconType="solid" size={16} color="#64748B" />     | Native ES modules / Node addon                                     | Forst → Go → addon → ESM path; design exploration only.                                                      |

## Tooling

| Status                                                                  | Feature                                                                        | Notes                                                                                                                                               |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| <Icon icon="circle-check" iconType="solid" size={16} color="#16A34A" /> | [`forst lsp` core (HTTP)](/docs/workflow/editor)                                    | Diagnostics, hover, completion, definition, references, rename, symbols, folding.                                                                   |
| <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" />        | [LSP Go interop hover](/docs/workflow/editor)                                       | Godoc and `go/types` signatures for qualified imports; module-level typecheck for cross-package Forst siblings. Go `pkg.` completion not yet.       |
| <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" />        | [LSP formatting and code lens](/docs/workflow/editor)                               | Format document advertised; code lens and some code actions still minimal.                                                                          |
| <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" />        | [VS Code extension](/docs/workflow/editor)                                          | Marketplace + Open VSX publish on `vscode-forst-v*` releases.                                                                                       |
| <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" />        | [`forst test`](/docs/workflow/cli#forst-test)                                       | Discover `Test*` in `*_test.ft`, emit Go tests and cross-package shims, run `go test`. Primary use: Providers wiring and cross-package integration. |
| <Icon icon="circle-check" iconType="solid" size={16} color="#16A34A" /> | [CLI (`run`, `build`, `generate`, `dev`, `lsp`, `test`, `fmt`)](/docs/workflow/cli) | Core compiler commands via native binary or `@forst/cli`.                                                                                           |
| <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" />        | Error message quality                                                          | Incremental improvements; diagnostics still vary by code path.                                                                                      |

## Infrastructure

| Status                                                                    | Feature            | Notes                                                                           |
| ------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------- |
| <Icon icon="circle-check" iconType="solid" size={16} color="#16A34A" />   | CI pipeline        | GitHub Actions: coverage (`task ci:test`), E2E (`task ci:e2e`), compiler build. |
| <Icon icon="circle-check" iconType="solid" size={16} color="#16A34A" />   | Release automation | release-please, git tags, npm/JSR publish workflows.                            |
| <Icon icon="hourglass-half" iconType="solid" size={16} color="#CA8A04" /> | Test coverage gate | Colocated Go tests and merged-statement coverage targets still expanding.       |

## Docs

| Status                                                              | Feature                                  | Notes                                                                                                        |
| ------------------------------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| <Icon icon="flask" iconType="solid" size={16} color="#7C3AED" />    | [This docs site (Mintlify)](/docs/quickstart) | Quickstart, language guides, interop, and workflow pages. Broader tutorials and migration guides still open. |
| <Icon icon="calendar" iconType="solid" size={16} color="#64748B" /> | Contributing guide                       | Doc contribution notes exist; full dev-setup `CONTRIBUTING.md` still planned.                                |

## What Forst omits

These are deliberate **anti-features**—not backlog gaps. Forst excludes them when they would hide control flow, surprise with errors, or break compile-time reasoning.

| Status                                                         | Topic                                      | Notes                                                                                                                                                                   |
| -------------------------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <Icon icon="ban" iconType="solid" size={16} color="#DC2626" /> | `panic` / `recover` as language constructs | Non-local, implicit control flow. Forst steers toward explicit `Result` and Go `error` returns. Generated Go or third-party code may still panic.                       |
| <Icon icon="ban" iconType="solid" size={16} color="#DC2626" /> | Exceptions (`try` / `catch` / `throw`)     | Stack-unwinding surprises. Aligns with Go `(T, error)` and `Result(S, F)` instead of TS/Java-style exceptions.                                                          |
| <Icon icon="ban" iconType="solid" size={16} color="#DC2626" /> | Class hierarchies and deep inheritance     | Inheritance obscures which fields an API has. Forst favors structural shapes and function-centric APIs.                                                                 |
| <Icon icon="ban" iconType="solid" size={16} color="#DC2626" /> | Macros and preprocessors                   | Control-flow changes must use ordinary keywords, not compile-time rewrites that hide behavior.                                                                          |
| <Icon icon="ban" iconType="solid" size={16} color="#DC2626" /> | Runtime reflection for wiring              | Providers, constraints, and obligation tracking are compile-time—not discovered via introspection at runtime.                                                           |
| <Icon icon="ban" iconType="solid" size={16} color="#DC2626" /> | TypeScript-style `undefined`               | No dual null/undefined universe. Optionals direction is `Nil` and absence—see [optionals RFC](https://github.com/forst-lang/forst/tree/main/examples/in/rfc/optionals). |
| <Icon icon="ban" iconType="solid" size={16} color="#DC2626" /> | Implicit numeric widening                  | Silent `int`↔`float` (and similar) conversions are rejected; casts stay explicit.                                                                                       |
| <Icon icon="ban" iconType="solid" size={16} color="#DC2626" /> | Dependent types and type-level computation | No type families or template metaprogramming—keeps typechecking decidable and tooling fast.                                                                             |
| <Icon icon="ban" iconType="solid" size={16} color="#DC2626" /> | Runtime type mutation                      | No monkey patching; type definitions are fixed at compile time.                                                                                                         |

## Full roadmap

<Card title="ROADMAP.md on GitHub" icon="github" href="https://github.com/forst-lang/forst/blob/main/ROADMAP.md">
  Feature parity tables, experimental gaps, RFC links, and infrastructure status.
</Card>

Report bugs and gaps as GitHub issues when shipped features do not match the **done** bar.