EN
Project
  1. Design records

Roadmap#

Status: planned — the milestones that are still ahead, each with its goal and the design records that specify it. Milestones 1 to 6 are done (ARCHITECTURE.md, "Milestones"): the compiler is written in TorbScript, compiles itself, and builds native programs through C. Nothing here has a date; a milestone is finished when its gates are green.

The order is the order of dependence. Milestones 7 and 8 are the core, and the public release of design/RELEASE.md is gated by them. Milestones 9 and 10 are additions a minor release may bring, so neither blocks 1.0. Beside the milestones, a few packages and language features are designed and wait for a slot; they are listed after the milestones.

This page keeps the direction, not the work list. Every open piece of work is an issue of the project's tracker, git.torb.dev/torbscript/language/issues, and each phase below is a milestone there; the tracker is the one place that says what is open and what is done. A design record stays the specification of what an issue builds, and its slice table says how far it got.

The releases follow the calendar since 2026-09-29 (design/RELEASE.md section 3): 0.1.0-rc.1 on 2026-09-29 and 0.1.0 on 2026-10-06, then a minor on the first Tuesday of every month, each a week earlier as a release candidate on the preview channel, and a patch whenever a fix is ready. A milestone decides what a minor carries, not when it comes; 1.0 is gated by its list in RELEASE.md section 2, not by a date.

The public release also carries the brand of design/BRAND.md: the logo, the icons and the design tokens are in brand/, and applying them to the website, the registry, the forge, the colours of torb's output and the VS Code extension is that record's five slices (section 13).

Milestone 7: the VM, tasks and the sandbox#

Goal: the same program runs interpreted and compiled, with the same output, and torb run needs no C compiler. The bytecode VM interprets the same IR the C back end compiles, and the conformance suite holds both to one behaviour. The core of the milestone is done: every conformance program runs in both back ends with the same output, exit code, panics and leak count, torb run and torb test run in the VM by default and torb build stays native. Tasks, channels and the worker pool run in both; the streams of File and of the three standard streams are built on the blocking pool beside the IO poller of sockets, and the pipes of Process.start on that poller where it takes them (Linux, macOS, FreeBSD) and on the blocking pool on Windows; a program the VM runs loads receiver scripts from paths only known while it runs; torb build --embed-vm builds a native binary that embeds the VM; and the REPL has every slice of REPL.md. A native binary loads and applies receiver scripts through the script host it links, the value encoded across (SCRIPTS.md slice 8), and the toolchain reads an evaluated manifest where a setting it uses is computed (SCRIPTS.md slice 5). Open work: the issues of the milestone Milestone 7 - the sandbox's own heap, the parallel Plain and Window, the measurements of CONCURRENCY.md slice H, the sandbox's network grant and the VM's next speed steps. The gates of slice G are written: eight files read at once and a cancelled read on each wait mechanism.

Milestone 8: formatter, linter, language server, package manager#

Goal: the tools a user expects around a language that is meant to be used.

  • torb format - built: every rule of the canon, then indentation, spaces, blank lines and a width of 120 columns - a long line breaks at the outermost bracket that makes it fit, and what the formatter broke joins again once it fits - over the syntax tree with the safety net of the canon; format --check is the tier A gate, and torb canon is a deprecated alias of it (tooling/torb-format.md).
  • torb lint - built, with --fix as the migration tool for every breaking change before 1.0 and for every deprecation after it: the rules self-name, question-field, unread-binding, labeled-literal and redundant-closure, swept over the standard library and the compiler, deprecated, which moves every use of a deprecated declaration to its replacement (design/DEPRECATION.md), and torb rename for a field renamed at every use the checker resolves (tooling/torb-rename.md, tooling/torb-lint.md).
  • The language server is the compiler - the second round is built (2026-09-28): torb lsp over standard input and output, the diagnostics of check with their ranges for the open documents and, in the background, for every file of the workspace, hover from the model of torb doc, go to definition, the references, a rename that is checked before it is made, completion with the documentation of each item, signature help, the symbols of a document and of the workspace, the formatting of torb format, semantic tokens from the highlighter sharpened by the checker, and the lint fixes as quick fixes; a keystroke inside of a function checks that function and keeps the check of the rest of the file, long work runs in steps between the messages and can be cancelled, and every folder of a workspace is a project of its own. The VS Code extension in editors/vscode is its client (tooling/torb-lsp.md, design/LANGUAGE-SERVER.md), published with every release (2026-09-28) to the Visual Studio Marketplace and Open VSX as torbscript.torbscript, with the Test Explorer (torb test --report json), Format Document, and a walkthrough that installs the toolchain (how-to/set-up-your-editor.md). The debugger is built as well (design/DEBUGGER.md).
  • The package manager: the manifest that is evaluated, the lock file, add, remove, update, publish, and the registry at packages.torb.dev (design/PROJECT.md section 12, design/RELEASE.md section 7). The client is built (2026-09-26): torb add, remove, update, install and publish, PubGrub resolution with its explanations (PROJECT.md section 6a), project.lock.trb written deterministically and read by the build, archives with their tree hash checked on every install, curl/wget or a file: registry, a content-addressed cache and --offline; std/digest, std/compression and std/archive came with it (RELEASE.md section 7.13). The write service is built (2026-09-27): tools/registry, the first TorbScript server - accounts, owners, scoped tokens, publish, yank and trusted publishing from GitHub Actions and Forgejo Actions over /api/1, SQLite through the sqlite3 shell, the index and archives through a file: storage driver of URI.md section 11, the index mirrored into git - and torb publish uploads to it with TORB_TOKEN or a CI identity; its images are pushed to cr.torb.dev by every release and nightly, and tools/deploy/compose.example.yml runs them behind the owner's Traefik with Litestream and restic (RELEASE.md section 7.11). The forge (2026-09-27): the repository, its CI, the seeds, the releases and the images live on the project's own Forgejo at git.torb.dev and cr.torb.dev, GitHub is a push mirror whose one workflow tests the targets the forge has no runner for yet, and the installers and package manifests download from torb.dev (RELEASE.md section 14). The index is signed and checked since 2026-09-27 (std/signature, RELEASE.md section 7.14), and torb lock [--check] is a gate of tier A. A lock's settings close with the files and variables the evaluated manifest read, in from { } by the hash of the bytes, or of name and value, and torb publish names them (2026-10-12 and 2026-10-21, PROJECT.md section 8). torb login and logout store a token for the user, and torb owner and torb yank speak to the registry's API with it (2026-10-09, RELEASE.md section 7.13), and torb deprecate flags a whole package, which torb add announces (RELEASE.md sections 7.3, 7.4 and 7.13). Two majors of one package in one graph are built (2026-10-14, PROJECT.md section 6a): the checker, lowering and every back end keep them apart under name@major. The bug found on the way - std/network's name resolution crashed a program on Windows for a host that needs a DNS lookup - is fixed (RELEASE.md section 7.13).
  • torb doc is built: the reference of a package as a static site or as JSON, and the examples of its doc comments as doc tests (tooling/torb-doc.md). The language server's hover reads the model since 2026-09-28. The check is strict since 2026-10-19: a public construct without a doc comment fails torb doc --check.
  • The natives that are declared and planned: the full Unicode tables, which the 1.0 list of RELEASE.md section 2 needs. Decimal is built (specified in design/DECIMAL.md, four slices, the last on 2026-10-28). Float32 arithmetic, compare, Show and the narrowing from a Float64 are built (2026-10-12). get, post and send of std/http are built, in TorbScript on Uri.

Open work: the issues of the milestone Milestone 8 - the rest of the linter and the language server, the registry's sign-in, documentation worker, search and owners, the package manager's remaining commands and sources, the debugger's open points, the declared natives, and the forge's runners and theme, which need the forge's administrator. The prelude rule of the 1.0 list is built (2026-10-12, CONCEPT "Imports").

std/yaml and std/markdown come before it, because torb doc and the hover of the language server render Markdown (design/TEXT-FORMATS.md).

The kernel of natives#

Goal: a new back end starts from a short, fixed list of IR intrinsics, and everything else in std is TorbScript. Every native of std/ is work for every back end, so before milestone 9 the manifest of natives (compiler/src/backend/c/natives.trb) is audited and reduced to a kernel: integer and float arithmetic, comparisons, raw storage, bytes to numbers. The body of a native fn becomes IR, and native { ... } a block of IR inside an ordinary function (CONCEPT, "Foreign Functions"; specified in design/NATIVE-BODIES.md), so std/ itself says which operation Int64.add is. Buffer<Item> joins Array in std/core as the heap storage primitive, and ArrayList, the hash tables and the tries are rebuilt on it in TorbScript (design/COLLECTIONS.md, gap 6). A back end may still replace an ordinary function by something faster; that is its private business.

The performance work that waits for a second back end belongs here too: steps P9 to P12, an allocation budget per conformance program as a gate, and torb build --explain-copies (PERFORMANCE.md), which is built (torb-build.md).

The audit of every native, with its verdict and the closed list of the kernel, is design/NATIVES.md. The rewrite of the collections on Buffer, with its slices and its cost bounds, is design/COLLECTION-STORAGE.md.

Open work: the issues of the milestone Kernel of natives.

Milestone 9: JavaScript and PHP#

Goal: TorbScript compiles to JavaScript, so the front end of an interactive application is written in the same language as its server, and to PHP, so a program runs on a classic shared web host. Both keep the language's semantics rather than the host's: fixed integer widths, and reference counting where close() has to run at a known line. Tasks become promises in JavaScript and run on an event loop in PHP that uses what the host has. A capability table per target says which package is real, simulated or a compile error at its import, and packages for npm and Composer are generated where the public interface allows it.

Open work: the issues of the milestone Milestone 9, starting with the one open question of the record, the oldest supported PHP.

Milestone 10: the breadth of the standard library#

Goal: a standard library on the level of a platform, as separate packages of std, each of them pure TorbScript on the natives that exist. In this order, because each part stands on the one before it:

  1. File systems. std/fs stays the native driver on Path. Above it, a storage layer chooses a driver by the scheme of a URI - local files, memory for tests, then S3 and WebDAV as packages of their own - and std/fs gains remove and rename (design/URI.md sections 11 and 14, design/PATH.md). Connections to databases and caches are URIs whose scheme chooses the driver in the same way. Built (2026-09-27): std/fs has the synchronous readBytes/writeBytes beside the task read, remove, removeDirectory, rename, copy, walk, metadata and linkMetadata with Metadata, FileKind and Permissions, setPermissions, symbolic links, temporary files and directories and writeBytesAtomically - one text form on every system, converted in runtime/platform.c, so the compiler's C stays the same for every target (the package manager reads and writes its archives with them, and its od/PowerShell detour is gone; torb upgrade hashes with std/digest, unpacks with std/archive and places, links and mirrors the toolchain with them, running only curl); std/time has Timestamp; a var file handed to a var Sink parameter builds in both back ends; and std/storage has Storage, StorageFailure, Storage.registry, FileStorage and MemoryStorage over Schemes of std/uri (URI.md slice 12). Connection and Cache wait for a second driver each.
  2. The network. std/network (sockets), then std/http (client and server, TLS through the platform), then gRPC and OpenAPI on top of it. std/uri is finished before std/http grows further (the owner, 2026-09-25): the URI types, IRIs, URNs, templates and the pure address package std/ip come first (design/URI.md section 14). The pure std/dns - names with IDNA, records, the wire format - is built, and so are its first transports: lookup(name, type) over UDP and TCP (RFC 7766) with the system's name servers in std/network, DNS over TLS (RFC 7858) in std/tls and DNS over HTTPS (RFC 8484) as DohResolver in std/http; a Client that connects through a resolver and the HTTPS/SVCB records for ALPN (RFC 9460) come next (design/DNS.md section 7). The web layer above HTTP - handlers, routes, HTML and a live UI - is design/WEB.md.
  3. Formats, as packages on Encode and Decode (design/ENCODING.md section 9): json and toml exist, std/json-schema is started (validation of the in-place keywords of 2020-12; references, the unevaluated keywords and the earlier drafts are still to come), then xml and html (the document formats, each with its tree) and JSON Patch, in the versions of the table below. yaml, regex and markdown come earlier (design/TEXT-FORMATS.md).
  4. Computation and machine learning on std/linear and std/geometry, which exist (design/LINEAR.md): std/tensor (design/TENSOR.md), std/gradient (Dual, forward mode, is built), std/gpu and std/learning (design/COMPUTE.md).
  5. The application framework: the scope of Spring Boot or Symfony, wired at compile time through traits, constructors and a module DSL instead of annotations and reflection (design/FRAMEWORK.md).
  6. Language models and agents: std/language-model with clients for the important providers over one streamed protocol of messages and threads, and std/agent, an agent framework after the model of pi (design/LANGUAGE-MODELS.md).
  7. The engine packages, last: std/ecs, std/scene, std/transform, std/collision, std/animation, std/render and std/input, independent of any one graphics interface (design/ECS.md). They share std/linear, std/geometry and std/gpu with the computation of part 4.

Open work: the issues of the milestone Milestone 10, among them the gaps of std that the first-party packages of design/FIRST-PARTY.md section 8 name.

Which versions a format supports#

A format package reads its current version and every earlier version that a large share of the documents in circulation still uses, and writes the current version unless the caller asks for an earlier one (the consumer of a document is often older than its producer). The versions of one format share one model: an earlier version is read into the model of the current one, not into a second set of types. A version that is no longer written is not supported, and neither is a dialect with its own name.

FormatSupportedNot supported
YAML1.2, 1.1 (design/TEXT-FORMATS.md)1.0
JSONRFC 8259, and JSON Lines as a stream of valuesJSON5, HJSON
TOML1.0 and every later 1.xthe 0.x drafts
XML1.0 (fifth edition) with namespaces; a DTD's entities are read, an external entity is never fetched1.1, validation against a DTD
HTMLthe parsing algorithm of the WHATWG standard, which also reads older documentsa separate HTML 4 or XHTML parser (XHTML is XML)
JSON Schema2020-12, 2019-09, draft 07 (draft 06 is read as 07), draft 04 (the dialect of OpenAPI 3.0 and Swagger 2.0)draft 03 and older
OpenAPI3.2, 3.1, 3.0; Swagger 2.0 is read into the 3.x modelwriting Swagger 2.0
JSON PatchRFC 6902, and JSON Merge Patch (RFC 7396)
Protocol Buffersproto3, proto2 and the editions
MarkdownCommonMark with the tables of GitHubother flavours

Packages designed outside the milestones#

These have no milestone; their issues are in the tracker without one.

PackageWhat it isRecordOpen work
std/yamlbuilt: YAML 1.2 and 1.1 in full, anchors, aliases, tags and comments in the tree, the target type resolves scalars, a schema is an option; all 402 cases of the YAML test suite passdesign/TEXT-FORMATS.md section 1a-
std/tomlbuilt: TOML 1.0 and 1.1 read as a tree and through Encode/Decode, dates and times with nanoseconds and offset, a writer for either version; the reader passes the toml-test suite and every valid case writes back as an equal treedesign/ENCODING.md section 9-
std/regexbuilt: a Regex with RE2's syntax and linear time, groups by name that decode into a type, replace and split; RE2's search tests pass; a literal where a Regex is expected is compiled by the checker, read verbatimdesign/TEXT-FORMATS.md section 2a-
std/markdownbuilt: CommonMark 0.31.2 with GitHub's tables and front matter, the document tree as a value with the lines of its blocks and links, HTML and a writer that round trips; all 652 examples of the specification passdesign/TEXT-FORMATS.md section 3a, design/RELEASE.md slice 1-
std/randombuilt: Random, a seedable, splittable SplitMix64 generator that is a value, with the integers of a range, floats, shuffling, choice, sampling and splitting; normal and the other continuous distributions wait for std/statisticsdesign/RANDOM.md section 2-
std/identifierbuilt: Uuid (RFC 9562 versions 4 and 7), Ulid, the trait Identifier, IdentifierError and the urn:uuid: bridge to std/uri; randomness and the clock are arguments, so the package has no capabilitydesign/URI.md section 12-
std/uribuilt: Uri and UriReference after RFC 3986, IRIs (RFC 3987), Urn (RFC 8141), DataUri (RFC 2397), UriTemplate (RFC 6570) typed against the fields it fills, routes (route, TemplateRoutes), the file: bridge, std/ip, std/http on Uri, Host.domainName(), the literal rule (Path, Uri, UriReference, UriTemplate, Regex, resources), and non-ASCII hosts through std/dns's IDNA with U-labels in iriText()design/URI.md section 14#132, #134
std/dnsbuilt: DomainName with IDNA (Punycode, UTS #46 as far as std/text's tables reach) and RFC 4343's comparison, the records as typed cases, Message with compression and EDNS0, query and readResponse; lookup and Resolver over UDP and TCP with the system's servers in std/network, TlsResolver (DNS over TLS) in std/tls, DohResolver (DNS over HTTPS) in std/http; DNSSEC validation is outdesign/DNS.md section 7in milestones 8 and 10
std/clicommands, flags and options declared once, help and errors generateddesign/CLI.md#123, #124, #125
std/os, std/paththe rest of their slicesdesign/OS.md, design/PATH.md#126 to #131
resourcesfiles a program ships or embeds, named by a literal; slices 1 and 3 built (std/resource, the literal resolved and checked by the compiler; torb build ships Resource files beside the binary, Resource.bytes()/text() read them)design/RESOURCES.md#135 to #138
collectionsbuilt: RingList, ConsStack, BankersQueue and Heap, and the visibility of the stagesdesign/COLLECTIONS.md, C7 and C8#139, #140

Language features designed and not built#

FeatureRecord
The candidates without a decision: let-else, variadic type parameters, _ as a type argument, fields on one line, and othersCONCEPT, "Open Questions"

The principle for where a program may panic (design/PANICS.md) and the words per kind of collection (design/COLLECTIONS.md, C2c and C9) are built, and a public enum does not grow (RELEASE.md section 2). Loops as expressions (design/LOOPS.md) are not on this list: the owner deferred them on 2026-09-29, and loops stay statements.

CONCEPT's "Open Questions" stay there: they are questions for the owner, not work, until one is decided.

Esc
Enter opens a resultEsc closes