Releasing TorbScript#

Status: planning; the CI and the release pipeline of section 13 are built, and since 2026-09-27 they run on the project's own forge at git.torb.dev (section 14) — this record plans the public release of the language: what has to exist first, what a download contains, the website at torb.dev and the package registry at packages.torb.dev. Apart from section 13 and the package manager's client of section 7.13, no command, page, server or file described here exists yet, the domain serves nothing, and nothing has been registered, published or announced. Every statement about what the repository does today comes from section 1, which was measured on the commit this record was written on (653af8bb).

A release is three launches, not one, and each has its own gate. The preview publishes the language: downloads, installers and the documentation at torb.dev, with dependencies only through path:, git: and workspaces. The registry opens packages.torb.dev once the package manager of milestone 8 can talk to it. 1.0 is a promise about compatibility, and it is given once the language has stopped changing weekly — not on a date. Everything the three need that does not block core work can be built now, in the order of section 10.

                         torb.dev                                   packages.torb.dev
  ┌──────────────────────────────────────────────────┐   ┌──────────────────────────────────────────────┐
  │ /             landing                            │   │ /acme/http             a package's page      │
  │ /install      the one-line installers            │   │ /acme/http/1.2.5/docs  torb doc, generated   │
  │ /download     every artifact, hashes, signatures │   │ /index/acme/http.trb   the sparse index      │
  │ /learn        the guide and the tour             │   │ /archives/...          immutable source      │
  │ /docs/<ver>   reference, std, tooling            │   │ /api/1/...             publish, yank, owners │
  │ /play         the VM in the browser              │   └──────────────────────────────────────────────┘
  └──────────────────────────────────────────────────┘        read: static files behind a CDN
        generated by `torb docs site` from docs/               write: one small service, `torb publish`

• 1. Where the repository stands — eighteen facts, measured
• 2. Readiness — what each of the three launches needs, by milestone
• 3. Versions and the stability promise — the 0.x period, what 1.0 promises, no editions, pre-releases and the monthly cadence
• 4. What a download contains — the binary, std/, runtime/, and the C compiler question
• 5. Installing, upgrading, channels and signing
• 6. The website — torb docs site, versions, search, the playground, hosting
• 7. The registry — owners, publishing, the index, security, capabilities, policies
• 8. Terminology — package, project, workspace, module, library
• 9. Governance and legal
• 10. Slices — from now to each launch
• 11. What this is not
• 12. Open — the questions for the owner
• 13. The release pipeline, as built — CI, the published seed, nightlies, releases, signing
• 14. The forge — git.torb.dev and cr.torb.dev, runners, the tokens of Authorized Integrations, GitHub as a mirror, security

1. Where the repository stands#

Facts 3 to 5 are the reason the preview is not "tag a commit and upload the binary": what runs today is one target, verified on one machine.

2. Readiness#

Decision: the three launches have three lists, and an item belongs to the earliest launch that cannot do without it. The milestones are the repository's own (docs/ARCHITECTURE.md: 7 is the VM, tasks and the sandbox, 8 the formatter, the language server and the package manager, 9 the JS and PHP back ends, and 10 the breadth of std; docs/ROADMAP.md lists them).

The preview: torb.dev with downloads and documentation#

Not needed for the preview: the registry, the language server, torb format (torb canon enforces the canon and says it is temporary), Decimal, the REPL, milestones 9 and 10.

The registry: packages.torb.dev#

1.0#

Not needed for 1.0: milestone 9 (JS and PHP) and milestone 10 (the breadth of std), because both are additions a minor release may bring; the .torbc file format (VM.md section 1), which is a cache and never promised.

3. Versions and the stability promise#

Decision: one number, MAJOR.MINOR.PATCH, for the toolchain, the language and std together, which is what PROJECT.md section 10 already decided for language "0.3.0": "The language version and the std version always coincide, so the number is the language's". The download, torb --version, the language line and the documentation path /docs/0.4/ are the same number.

A pre-release carries a suffix after the number it is a candidate for (decided 2026-09-29): 0.1.0-rc.1, and before a major only 1.0.0-alpha.1 and 1.0.0-beta.1 besides the release candidates. SemVer orders it before its release (0.1.0-rc.1 < 0.1.0, rc.2 < rc.10, alpha < beta < rc), and torb upgrade, release-sync and the package manager (compiler/src/package/version.trb) order versions that way. The manifests, torb --version and the extension keep the number without the suffix: a release candidate is a build of that number, and where it becomes the release, the same commit is tagged again. A package's language line is therefore compared with 0.1.0 under 0.1.0-rc.1 as well - a candidate is meant to be tried with the programs that will run on its release.

Before 1.0, 0.MINOR may break and 0.MINOR.PATCH may not. That is Cargo's reading of semantic versions below 1.0 (^0.4.2 means >=0.4.2, <0.5.0), and the one the registry's resolution uses for packages too. Every breaking minor ships its migration: RUST-EXIT section 4.2 already requires the teaching commit to add the rewrite to torb canon (from milestone 8, torb format), so the migration exists before the break by construction. Release notes name each break and the command that migrates it. Only a minor breaks, so at most once a month (the cadence below), each break with an automatic migration - torb format or torb lint --fix - named in the release notes; within 1.x nothing breaks.

What 1.0 promises, written in the style of Go's compatibility document:

No editions. The language line stays a minimum version, which is what PROJECT.md section 10 decided, and not a switch between dialects.

The cadence — decided by the owner's delegation (2026-09-29), by the calendar; it replaces the six weeks the owner first chose (question 4 of section 12).

• A minor every month, on the first Tuesday. A week before - on the Tuesday before the first Tuesday - the branch release/0.N is made from main and v0.N.0-rc.1 is tagged on it; main moves on at once and carries the next number. Without a blocker the release candidate becomes the stable release unchanged: the first Tuesday tags the same commit v0.N.0. A blocker is fixed on main, cherry-picked onto release/0.N, and the next candidate -rc.2 is tagged there; the stable release is always a candidate that was out first, and only a blocker that is not fixed by the first Tuesday moves the date. A release candidate is the preview channel (section 5).
• A patch (0.N.1) whenever the fix of a regression or of a security problem is ready, from release/0.N: fixes only, never a break and never a feature, and no candidate.
• Alpha and beta exist only before a major (1.0, 2.0), and in that phase they replace the monthly minor: an alpha while breaks are still allowed, a beta once the surface is frozen, then a release candidate and the major.
• A nightly from every commit of main on which tier A and tier B are green, as before - nightly-YYYYMMDD, the tag installers, release-sync and the editor extension already rely on.
• Support: no long-term support release, as Go and Rust have none. In 0.x only the newest minor is maintained: release/0.N takes patches until 0.(N+1).0 is out. From 1.0 the newest minor gets every fix, and the one before it security fixes for one more month.
• Semantic versions, not calendar numbers. A number such as 2026.10 would say when a release was made; a semantic version says whether an update breaks, and the registry resolves packages by it (section 7). The date of a release is in its notes.
• The first release: v0.1.0-rc.1 on 2026-09-29, right after the pipeline learnt pre-releases, and v0.1.0 on the first Tuesday of October, 2026-10-06. Then 0.2.0-rc.1 on 2026-10-27 and 0.2.0 on 2026-11-03.

4. What a download contains#

Decision: an archive per target with the binary, std/, runtime/ and the licenses, laid out so that torb finds the rest beside itself — which is how compiler/src/project/toolchain.trb already looks for them, walking up from the binary to a directory with std/prelude/project.trb and runtime/include/torb.h.

torb-0.4.0-linux-x64/
├ bin/torb                    the toolchain (fact 1: 16 MB today on Windows)
├ std/                        every std package, as source: the checker reads it, the VM runs it, the C back end builds it
├ runtime/                    the C runtime: include/, *.c, os/*.c, without its tests - `torb build` compiles it with each program
├ tools/build-slot.sh         the machine-wide build slots of `torb build` (fact 6)
├ tools/build-units.sh        the parallel compile of a large program's units and the object cache (BACKEND 4.1)
├ LICENSE, NOTICE             section 9
└ README.md                   three lines and the link to torb.dev/learn

• The archive is .tar.gz everywhere and .zip on Windows as well, with a SHA256SUMS beside all of them and a signature (section 5).
• Two artifacts beside the per-target archives: the source of the tagged commit, and the compiler's program.c — the portable seed of RUST-EXIT section 4.1, "builds anywhere a C compiler exists". README.md already promises both ("A release publishes both artifacts").
• The Agent Skills (torb docs skill, committed in skills/) are not inside the toolchain: they are documentation, and an agent installs them from the repository where its harness reads skills - a Claude Code or Codex plugin marketplace, npx skills, APM (docs/site/agents.md).
• Nothing else. No bundled editor, no documentation in the archive (torb.dev has every version), no C compiler.
• The Windows torb.exe carries the Orb and its version (docs/design/BRAND.md section 11, "Binary icons"): tools/windows/torb.rc names brand/icons/torb.ico and the product name TorbScript, and tools/windows/resource.sh compiles it with the version of project.trb into an object file. The release step of .forgejo/actions/portable compiles the bootstrap's program.c again with that object linked (TORB_OBJECTS of tools/build-seed.sh), so the bootstrap, its fixpoint - which compares the C - and every program torb build writes stay without it. The resource compiler is GNU windres, which MSYS2's gcc brings on the Windows runner; without one the binary ships without its icon and the step warns. A program built with torb build gets no TorbScript icon: it belongs to its author.

The C compiler#

Decision: the download bundles no C compiler; torb run, check and test need none once they run in the VM (section 2); torb build finds the machine's compiler, and when there is none it says in one line how to get one, including a managed one that torb can fetch on request.

The question is real on one platform. On Linux a C compiler is one package away and usually installed; on macOS xcode-select --install gives clang; on Windows there is none by default, and MSVC's cl is not on the PATH outside a developer prompt, which is why torb build finds it only when someone set that up.

The release pipeline uses the managed compiler too. One pinned zig cc building torb for every target from one kind of runner is what makes section 5's reproducible builds a property of the pipeline and not of whichever runner image was current. The native runners of section 5 still run the gates, because a cross-compiled binary is not a tested one. As built (2026-09-29), a pinned zig cc builds the release binaries of the tier 1 targets the forge has no runner for, on its linux-x64 runner (section 13, "Cross-compiled archives"); linux-x64 and a target with a runner of its own ship the binary of their own machine.

5. Installing, upgrading, channels and signing#

Targets#

linux-x64 is built against musl and linked statically, so one binary runs on every distribution regardless of its glibc; the programs it builds link against the machine's own C library, because they are compiled by the machine's compiler. FreeBSD has no hosted runner on the common CI services and runs in a virtual machine on a Linux runner.

Installers#

• Both scripts are short, readable and served from torb.dev, never from a vendor's URL (section 6, "Hosting"). They detect the target, download the archive and SHA256SUMS, verify the hash, unpack, and write ~/.torb/install.trb (channel "stable" by default, method "script"), which torb upgrade reads.
• No stable release yet, the default channel: both installers, and torb upgrade left on stable, fall back to the newest preview and, without one, to the newest nightly, print one line saying which (no stable release yet: installing the preview 0.1.0-rc.1), and write that channel instead - the toolchain then follows it, with nothing more to type. Since the preview channel offers the stable releases too, a toolchain that fell back to it moves on to 0.1.0 once that is out, and to each later candidate after that; torb upgrade --channel stable leaves it. An explicitly requested channel or version is never substituted: it stays the error it already was ("no version of the ... channel is listed").
• A target missing from a version's archives is decided from that version's SHA256SUMS (downloaded first), never guessed from a failed download: "<version> has no <target> archive yet", naming both.
• A download with curl or PowerShell gets no quarantine attribute on macOS and no Mark of the Web on Windows, so the script path works without notarization or Authenticode. A binary downloaded in a browser is where section 5's signing matters.

torb upgrade#

Decision: torb upgrade exists, installs side by side, and never runs implicitly.

torb upgrade                     the newest release of the installed channel
torb upgrade 0.5.2               that version
torb upgrade --channel preview   switch the channel: stable, preview or nightly
torb upgrade --list              what is installed, and what is available

• Side by side: ~/.torb/toolchains/<version>/ holds each version, and ~/.torb/bin/torb is the one in use. A project that says language "0.5.0" under an installed 0.4 gets PROJECT.md's diagnostic plus one note: torb upgrade 0.5.0.
• Never implicit. Go 1.21 downloads the toolchain a module asks for; that is a fetch during a build, which PROJECT.md section 7 rules out for dependencies ("A fetch at compile time: never") and which this record rules out for the toolchain by the same argument.
• Only for a script install. torb upgrade in a toolchain installed by Homebrew, winget or a distribution reads install.trb, refuses, and names that package manager's command, as rustup does.
• On Windows the running torb.exe cannot be overwritten; it can be renamed, which is how the replacement is done.

Channels#

The preview channel replaces "no beta channel before 1.0", which the six weeks decided: a monthly minor needs a week in which a candidate meets programs, and the channel is that week. The installers take it with TORB_INSTALL_CHANNEL=preview, torb upgrade --channel preview follows it, and the images carry the tag preview. Nothing else gets a pre-release: a version in the Visual Studio Marketplace or Open VSX is MAJOR.MINOR.PATCH and nothing else, so 0.2.0-rc.1 would take 0.2.0 from its own release, and Homebrew, Scoop and winget follow stable releases only; what is ahead of stable reaches an editor through the nightly's .vsix. The word preview also names the first of the three launches (section 2); the channel is always written preview.

Reproducible and signed#

• The C is reproducible already: the fixpoint compares two program.c byte for byte, and the generated C carries "no path of this machine, no time and no build id" (PROJECT.md section 8). A release publishes program.c and program.hash, so anyone can check that the released C is what the previous release's torb emits from the tagged source.
• The binary is reproducible given the pinned compiler (section 4): CI builds every release twice on two runners and compares the archives, which also means archives carry fixed timestamps, sorted entries and fixed modes.
• Signatures: SHA256SUMS plus a keyless Sigstore signature made in CI with the pipeline's OIDC identity, verifiable with cosign verify-blob against the identity of the release workflow; GitHub's artifact attestations are the same mechanism. A long-lived signing key held by a person is exactly what keyless signing avoids. Superseded on the forge (section 13, "Signing"): Sigstore's certificate authority trusts no identity git.torb.dev issues, so the forge signs with a cosign key of the project, held as a secret of the repository.
• Platform signing is a question of money and not of design (question 7): macOS notarization needs a paid Apple developer membership, Authenticode needs a paid certificate or signing service. Both matter only for browser downloads and for the .pkg/MSI installers; every arm64 macOS binary must carry at least an ad hoc signature, which the pipeline checks.

Installers, torb upgrade and the package manager channels, as built#

tools/install.sh (Linux, macOS, FreeBSD, POSIX sh) and tools/install.ps1 (Windows, PowerShell 5.1+) exist and are release assets; both are short, read a target and a channel, download, verify and unpack, and nothing else - they print the profile line rather than writing it (POSIX) and extend the user PATH themselves (Windows, since that has no profile file to append to). Both take their base URL, channel and an exact version from an environment variable (TORB_INSTALL_BASE_URL, TORB_INSTALL_CHANNEL, TORB_INSTALL_VERSION; TORB_INSTALL_TARGET skips detection), which is what the tests below use instead of a second, test-only code path.

<base url>/versions.txt, decided here since section 7.4's format is for the package index and this is simpler: one release per line, <version> <channel>, the channel stable for 0.1.0, preview for a pre-release (0.2.0-rc.1, 1.0.0-beta.2: a - after the numbers) and nightly for nightly-YYYYMMDD. release-sync (section 7.11) writes it by rewriting the whole file on every release: the previous line for a version, if any, is replaced, and every channel's lines are kept newest first by SemVer's precedence - stable, then preview, then nightly - whatever order the releases were placed in, because install.sh/install.ps1 pick the first line of their channel. For preview they compare that line with the first stable one and take the stable release where its numbers are not below the candidate's, which is all SemVer's precedence needs between a pre-release and a release. torb upgrade (below) sorts every line of the manifest instead, by the package manager's Version, so it does not depend on that order.

The layout both scripts write, and torb upgrade (compiler/src/cli/upgrade.trb) manages afterwards:

~/.torb/toolchains/<version>/   one full toolchain per installed version (%LOCALAPPDATA%\torb\toolchains\<version>\)
~/.torb/bin/torb                 a symlink to the active toolchain's bin/torb (POSIX only)
~/.torb/active                   the version the symlink, or the Windows copy, is at
~/.torb/install.trb               channel = "stable"  method = "script"     (%LOCALAPPDATA%\torb\install.trb)

Windows has no per-user symlink without a privilege most machines do not grant, so its "one in use" is a copy at %LOCALAPPDATA%\Programs\torb (on the PATH) that torb upgrade mirrors from the new toolchain - every file copied over, whatever the new toolchain lacks removed, what robocopy /MIR would do - after renaming the copy's torb.exe, which may be the one running or another torb started from the copy, to torb.exe.replaced - section 5's "the running torb.exe cannot be overwritten; it can be renamed", exactly as decided above. The renamed executable is removed with the rest of what the new toolchain lacks, or, while it still runs, by the next upgrade renaming over it.

install.trb's fields are written key = "value", one per line - a format of its own, chosen because it is not a project.trb (nothing here is evaluated, and it is read before a version of the toolchain is even chosen) and not the lock's literal-call format either (PROJECT.md section 8), which is for a graph, not four settings.

torb upgrade is implemented exactly as decided above: torb upgrade [<version>] [--channel stable|preview|nightly] [--list], never implicit, refuses naming the package manager's command when install.trb says another method (brew upgrade torb, winget upgrade TorbScript.Torb, scoop update torb), and --list shows what is installed (from ~/.torb/toolchains) beside what the channel offers (from versions.txt), each release marked once it is installed and once more if it is the active one. Only downloading runs a program, curl/wget (Windows included: curl has shipped with Windows since 1803, so torb upgrade needs no PowerShell at all) - the tool tools/fetch-seed.sh already assumes on every target; std/http answers a task, which the compiler cannot wait for. Everything else is the standard library since 2026-09-27, the same code on every target - the system is asked at run time, so the compiler's C stays one file for every machine:

• Hashing is std/digest's Sha256 over the archive, read whole with File.readBytes (File.chunks() answers tasks, and an archive is some megabytes), where it was sha256sum, shasum or PowerShell's Get-FileHash.
• Unpacking is std/compression's Bytes.gunzipped and std/archive's untarred() and extract() (2026-09-28), where it was the system's tar: the GNU tar of a release with its paths of more than 100 bytes, the executable bit of bin/torb set with File.setPermissions, and an entry that would land outside of the toolchain refused before anything is written. The archive is inflated whole, in memory: a release of 30 MB unpacked takes some seconds.
• Placing: the archive is unpacked into <home>/tmp-<version>/ and renamed into toolchains/<version> in one step, so a download or an unpack that fails never leaves half a toolchain the next torb upgrade would take for an installed one; the scratch directory is removed afterwards, and emptied first where a stopped run left one.
• Switching on POSIX makes the new link as bin/torb.next and renames it over bin/torb (File.createSymbolicLink, File.rename), where it was ln -sfn: a torb started meanwhile finds the old toolchain or the new one, never none. On Windows File.rename sets the copy's executable aside and File.walk, copy and remove mirror the copy, where it was cmd /c move and robocopy.
• active and install.trb are written with File.writeTextAtomically, so they hold the old value or the new one and never a part of either.

Package manager channels (winget, Scoop, a Homebrew tap - the preview's choice, section 5's table): rendered from tools/homebrew/torb.rb.template and tools/scoop/torb.json.template by tools/render-package-manifests.sh (its placeholders filled from the release's own SHA256SUMS, nothing recomputed), and pushed by the publish-packages job of release.yml, after the release. Since the move to the forge (section 14) every URL in them is https://torb.dev/download/<version>/..., where release-sync places each release, never a forge's; the tap and the bucket are repositories of the forge (torbscript/homebrew-tap, torbscript/scoop-bucket), pushed with the token of the Authorized Integration that publishes the release and mirrored to GitHub, where brew tap torbscript/tap finds the tap without a URL. A manifest is rendered only when the release has every archive it names - the formula needs macos-arm64, linux-x64 and linux-arm64, the bucket windows-x64, which every release has since the archives of the targets without a runner are cross-compiled (section 13) - and a channel whose repository does not exist yet is skipped: a channel must never hold back the release. winget stays a manual step while the forge has no Windows runner (wingetcreate runs on Windows only); the job prints the command. Nightlies publish nothing here: nightly.yml does not call this job. What the owner sets up once for these three is docs/contributing/releasing.md.

Tested: sh -n tools/install.sh (shellcheck where the machine has it), a full run of install.sh against a locally packed archive through TORB_INSTALL_BASE_URL=file://... and TORB_INSTALL_TARGET - the fallback to nightly (no stable line), the missing-archive error (a target SHA256SUMS does not list) and success - and the same three against the live torb.dev while there is no stable release. install.ps1 was run both piped into iex and as a file, against a local fixture through TORB_INSTALL_BASE_URL=file:///... (Invoke-WebRequest reads file:// in Windows PowerShell 5.1, so no HTTP server is needed): the fallback, the missing archive, a hash that does not match, and success, each confirmed to leave the caller's $ErrorActionPreference and scope exactly as they were - the point of running the whole script inside its own & { ... }. compiler/tests/upgrade. test.trb covers the pure parts of torb upgrade (parsing install.trb and versions.txt, comparing versions, reading SHA256SUMS) and, each in a temporary directory, hashing a file, unpacking with std/archive - a path of more than 100 bytes, the executable bit, an entry outside refused - and placing the toolchain, switching the link, and setting aside and mirroring the Windows copy. A whole torb upgrade - --list, an install, a hash that does not match, an upgrade run by the copy's own torb.exe, an installed version made the one in use again, --channel nightly, and the refusal for winget - ran on Windows on 2026-09-27 against a file:// base URL (TORB_UPGRADE_BASE_URL) with LOCALAPPDATA pointing into a scratch directory, which is how it is repeated. The POSIX branch beyond its tests, and a release on torb.dev, wait for a packaged release and a second machine.

The preview channel, tested (2026-09-29): compiler/tests/upgrade.test.trb orders pre-releases by SemVer (0.1.0-rc.1 < 0.1.0, rc.2 < rc.10, alpha < beta < rc), lets the preview channel offer the stable releases, and chooses a release for every channel with and without the fallback of the default channel; tools/release-sync's tests list a pre-release as preview between the stable lines and the nightlies, never point latest at it, and have the periodic check place the newest one. install.sh and install.ps1 (Windows PowerShell 5.1, and piped into iex) each ran 30 cases against a file:// fixture whose versions.txt held every combination of stable, preview and nightly lines - the default channel falling back to the preview and then to the nightly with its one line, stable, preview and nightly asked for explicitly, a candidate behind its stable release, and each missing channel's error - with the installed version, the recorded channel and the unpacked bin/torb checked each time; the copy of install.ps1 that ran had its one line that writes the user PATH to the registry replaced by a message. A whole torb upgrade on Windows against the same fixture fell back to the preview, moved on to the stable release of that candidate and then to the next candidate, listed the preview channel, and refused an explicit --channel stable with nothing stable listed.

6. The website#

Decided (2026-09-26): the slogan is "One language, every layer.", and the category the site, the README and the repository description name is "a single-language ecosystem". The front page leads with the slogan; the category is the line under it and the text of the meta description.

The structure#

torb docs site#

Decision: the site is generated by the toolchain from docs/, as torb docs site <root> <out>, and is plain static files. The documentation system is already a TorbScript program with a schema, generated indexes, checked links and checked snippets (docs/contributing/); an HTML writer is one more output of the tree it already reads, beside skill and bundle.

• It needs a Markdown renderer, which is std/markdown (fact 15): CommonMark with tables and front matter, a document tree as a value, HTML output as its own step. That package is the first slice, and it replaces the reader in compiler/src/documentation/markdown.trb.
• Highlighting at generation time, no JavaScript for it: every trb block is highlighted by the lexer and torb highlight's semantic tokens, so the site colours a field and a case the way the editor does.
• The navigation is the index tree: docs/index.md, then each folder's index.md, ordered by order, which is exactly what torb docs index already computes. A page's status: planned or draft becomes a banner.
• Search is a generated index and a small script: title, summary, keywords and headings of every page, plus a term index of the bodies, as one static file per version; no search service. The keywords front matter every page already carries is what it ranks first.
• Versioned: /docs/0.4/ is generated from the tag and never regenerated; /docs/latest/ is the newest stable; /docs/nightly/ the nightly. A page that exists in the newest version links to it from the old one.
• Checked like everything else: torb docs site --check fails on a broken internal link of the output, and the site of main is built by the gates so it cannot rot between releases.
• The standard library's reference is generated, and its guide is written (decided 2026-09-26, when torb doc was built): torb doc std writes /docs/<version>/reference/ - an index per package, a page per module, every public construct with its signature, its doc comment, its sections and an anchor, and its own search - and the hand-written page of a package under /docs/<version>/std/ links to it. The link is the site generator's to write, from the package name in the page's front matter: a Markdown link from docs/ into generated output would be a link torb docs check cannot follow, and it would reach the skill and llms-full.txt, which have no site around them. Both are generated from one tag, so they cannot disagree about a version. The ## Declarations section of a package page stays written by hand for now, because it is what the skill and the bundle show a model; generating it from torb doc's model instead is a follow-up (torb doc --json already has every signature and comment it needs).
• A small hand-written stylesheet and no framework. The output has to be hostable anywhere (below), and a page is text, code and tables.

As built (2026-09-28): torb docs site <root> --output <dir> [--version <v>] [--brand <dir>] [--check] (docs/tooling/torb-docs-site.md) writes the front page from docs/site/home.md, /install, /imprint and /privacy from the pages of the same name in docs/site/ where they exist, every page and design document below /docs/<version>/ with the navigation of the index tree, previous and next links and an edit link to the forge, search-index.json (the term index above), and one stylesheet and one script. trb blocks are coloured by the lexer and the resolver at generation time; every internal link of the output is checked. The Markdown is std/markdown's tree with a renderer of the site's own (anchors, callouts, the rewritten links), not its HTML step. site/ pages have the kind site and stay out of the skill and the bundle. The site image runs it from the release's source (tools/deploy/Dockerfile.site), and nginx serves it with clean URLs - a flat page's own trailing slash (/play/, /de/play/) redirects to the page without it, which is the one the site writes. /play is site/play.md with the playground (below).

docs/versions.json ([SiteVersions] of site.trb) is written once, at the root, the same for every language: today it names only the one version this build is of, because the site image bakes in exactly one version per deploy and nothing yet accumulates a running site's history across deploys (below) - so the switcher, seeing nothing to switch to, hides itself instead of the 404 it was reading before. docs/latest/ is a symbolic link Dockerfile.site makes after copying the built site in, one per language directory the site was written in (find ... -name "$VERSION"), so /de/docs/latest/ resolves exactly as /docs/latest/ does.

Not built yet: /learn, /download, /releases/<version>, a site that accumulates more than the one version of its own deploy (which is what a real docs/versions.json needs), and a version's link to the same page in the newest one.

The playground#

Decision: the whole toolchain compiled to WebAssembly and run in the browser — check, lower and run in the VM — with no server.

• A target is needed for it. A wasm torb is a new target, so OperatingSystem gains a case (fact 18), which is a breaking change of std/core and therefore belongs before 1.0. What each capability does there follows the rule of the JS back end (docs/design/JAVASCRIPT-AND-PHP.md): real, simulated (std/fs over an in-memory file system), or a compile error at the import (std/process).
• Sharing is the URL: the source compressed into the fragment (/play#code=...), which never reaches a server.
• Measured before it is built: the time torb check takes for a ten-line program with the prelude, natively, is the number the slice records first; if the prelude's check dominates, the playground ships the checked prelude as data.

The playground, as built (2026-09-28)#

playground/ holds it: build.sh builds the toolchain, playground.js, playground-worker.js, playground.css and the committed editor (playground-editor.js, .css and playground-codicon.ttf, built from editor/) are the page's side, examples/ is the gallery of /play, and smoke-test.mjs runs the result under node. The user's page is docs/tooling/the-playground.md; /play is docs/site/play.md. The editor, the language server and the gallery came a day later, below.

Measured first, natively (Windows x64, the torb.exe of dafd3138), a ten-line program with the prelude: torb check takes 600 to 680 ms, of which 440 to 510 ms is lexing and parsing, because a loose file's check reads the whole standard library; torb run --timings - what the playground runs - checks in 228 ms (144 ms of it parsing the modules the program reaches), lowers in 102 ms and reaches the first instruction after 379 ms. The prelude's check is about half of that and does not dominate the way the decision feared, so the playground ships no checked prelude: in the browser a warm hello world prints after 0.3 s, and a snapshot of the checker would be a format of its own to keep in step with the compiler. It is the first lever if the start ever needs to be faster.

The target is browser-wasm64. OperatingSystem gained Browser and Architecture gained Wasm64 (fact 18: a breaking change of std/core, made before 1.0 as decided above), torb build --target browser-wasm64 --emit-c emits C for it, and torb check --every-target lowers for it as its ninth target, as tools/agree.sh emits for it. std/os answers in the browser from std/os/src/browser/, with no natives: the system questions are Unsupported, pageSize is 65536, machineArchitecture is .Wasm64, Directories.temporary() is /tmp.

• Browser, not Wasi or Emscripten: the case names the system a program talks to, and the rule of the JS back end (docs/design/JAVASCRIPT-AND-PHP.md) is the browser's column; .NET names the same target browser-wasm (OperatingSystem.IsBrowser()), Go js/wasm. A later JavaScript back end for the browser has the same system.
• Wasm64, 64-bit pointers: the VM keeps a value in 64-bit words laid out as the runtime's own structs (VM.md section 2) - a String is two words that are a torb_text - which holds only where a pointer is a word. The C is compiled for wasm64 and lowered to wasm32 by binaryen (-sMEMORY64=2), so it runs on every engine, memory64 or not, and it is faster than real memory64, whose bounds are checked on every access: fibonacci(25) in the VM took 250 ms lowered and 350 ms with memory64 under node 24.
• The compiler's C for the target is the host's C everywhere but hostTarget(), whose one match OperatingSystem.current answers browser-wasm64 in the browser without starting uname; the machines' C stays the same for every machine, and the fixpoint is untouched.

The toolchain is emscripten 6.0.10, pinned in playground/build.sh and run from the image emscripten/emsdk:6.0.10 where no emcc of that version is installed. Over wasi-sdk it has, in one toolchain, what the runtime needs: setjmp over WebAssembly exception handling (-sSUPPORT_LONGJMP=wasm, the legacy instructions every engine since 2021 runs), the pthread stubs of a pool of one worker, the clock, randomness, an in-memory file system with std/ embedded at /torb/std, and the lowered wasm64. wasi-sdk would have needed a JavaScript host with a file system written by hand, and it has no wasm64. runtime/ needed three things: os/browser.c, the poller of the IO core that never opens; torb_platform_stack_low from emscripten's stack; one processor. TORB_HOSTS_MACHINE is set as for every torb. (Two more came with the language server, below: standard input the page feeds, and a turn to the blocking pool taken in place, because the pool's start panicked without threads - which had made every stream of std/io fail.)

The capability rule is enforced where the VM runs a program (compiler/src/project/capability.trb, reportMissingCapabilities in compiler/src/vm/run.trb): for the browser, an import of std/process, std/network, std/dns, std/http or std/tls in a file of the program is an error at the import, after the check and before the lowering; std/fs is emscripten's MEMFS, empty but for std/, with /torb/work as the working directory; the environment is empty and standard input at its end. Not in the lowering, because the compiler itself imports std/process and is built for the target; its natives link there and fail at run time, which no program of the playground can reach.

Size and speed, measured on the builds of 2026-09-28 and 29, on a machine that ran other gates at the same time:

The page's side is hand-written and small, and takes one pattern from each of the playgrounds it was measured against, and nothing more: a textarea over a coloured copy of itself (the Gleam tour's editor), in the token classes of the site so the colours are the site's; Run and Ctrl or Cmd+Enter (the Rust Playground); the output under the editor, the checker's lines marked in it with the message beside the line (the Go Playground); Reset and Show solution for an exercise, with a line that says whether it is solved (the Svelte tutorial); and the source in the address, deflated with the browser's CompressionStream and base64url behind #code= (the TypeScript playground's #code/), written as the reader types, so the address is the share button. A worker runs the toolchain, a fresh instance per run from the module the page compiled once, so Run can become Stop and a program that never ends never freezes the page; output beyond a megabyte stops the run. TorbPlayground.mount follows the contract of runnable blocks in torb docs site; a mount inside an element with data-playground-page is the page /play - the editor fills it and the address carries the source.

The site: torb docs site --playground <dir> (default build/playground beside docs/) copies the nine files and the folder examples/ into assets/ where they were built; no page names them, so a site without them is still whole. Every page then carries a hash of them (data-playground-version), the site's script loads assets/playground.js?v=<hash>, and playground.js hands its query on to the workers, torb.js, torb.wasm, the editor and the examples - so tools/deploy/nginx.conf lets a browser keep all of them for a year, like the stylesheet, and sends torb.wasm.gz with gzip_static. The site's labels of the playground are words of its interface (playground.* in site-strings.trb and each language's strings.json), and the line that says how to run an exercise of Start locally stays below the mount. The site image builds the playground itself, in the pinned emscripten image, from the release's source and with the release's torb - the same inputs give the same wasm, and nothing but the release is downloaded for it. CI's playground job (.forgejo/workflows/gates.yml) builds it in that image from the compiler of the run and runs smoke-test.mjs.

Not built: brotli (the stock nginx has no module for it; 30% smaller), a checked prelude (above), and keeping the compiled module between visits in IndexedDB (browsers no longer store a WebAssembly.Module there; the HTTP cache and the engine's own code cache do it).

The editor, the language server and the gallery, as built (2026-09-29)#

The owner asked for two things after the first playground: examples worth opening, shown sensibly, and a whole language server - completion, and the errors while typing rather than after Run. Both are built.

torb lsp runs in the page as it runs for an editor: over standard input and output, in a worker of its own. The server is already a value without a transport (LANGUAGE-SERVER.md section 3), so the question was only how the page reaches its standard streams, since nothing in a browser may block and a message reaches a worker only once its thread is back in the event loop.

The mechanism, in runtime/os/browser.c: the page's stdin callback answers undefined where it has nothing yet, so a read fails with EAGAIN as on a non-blocking descriptor; a read of standardInput() that meets it waits as an operation of the IO core (runtime/stream.c); where the main thread's scheduler would sleep while it waits, it returns to the page instead (task.c) - the first time by giving up the stack of main (emscripten_unwind_to_js_event_loop), with the program alive. torb_browser_resume(input), exported, wakes the read and runs the scheduler until it waits for the page again, and answers the milliseconds to its first timer, which the worker waits for with setTimeout. Natively a message waits for at most one step of the server's longer work (LANGUAGE-SERVER.md section 2), because the reader is a task of its own; in a page the reader can only be handed a message while the scheduler is out of the way, so tasks that run on and on return to the page after a slice of 50 ms as well, and the worker calls back at once, behind the messages that came meanwhile (the answer 0, a MessageChannel rather than setTimeout, whose clamp would cost a slice 4 ms). A hover sent in the middle of a rename, which takes 7 seconds in the browser because it checks the program twice, is answered within the next slice. A page whose stdin answers null - every run - sees standard input at its end, as before, and is never sliced. Process.exit from inside the server throws emscripten's ExitStatus to the worker, which tells the page; the page starts a new server and opens its documents again, up to three times. playground-worker.js has two roles now, a run and the language server, and smoke-test.mjs runs the worker itself in a thread of node's: initialize, the diagnostics of a document opened and changed, completion at a member access, hover, semantic tokens, a rename, and the exit.

The editor is CodeMirror 6 with @codemirror/lsp-client, 452 KB minified and 142 KB gzipped, loaded when an editor is about to be used. (A day later it became Monaco, below: "Monaco in every runnable block".)

What the editor adds to the client is TorbScript's, in playground/editor/editor.mjs: the colours - the lexer's of playground.js at once, sharpened by the server's semantic tokens where one covers the same name, so a parameter and a mutable binding look as they do on the site - the indentation of the formatter, brackets and comments, definition on Ctrl or Cmd and a click, and the Markdown of hover and completion sanitized to the elements of prose, because it comes from doc comments and a doc comment of a shared link is anybody's. A mount starts as the light editor and becomes CodeMirror at once on /play and at the first focus elsewhere, so a page of the documentation with ten runnable blocks loads neither the editor nor the toolchain until a reader clicks into one; the language worker is one per page and holds every mount as a document (file:///torb/work/main.trb on /play, block-<n>/<file> elsewhere). A run never waits for the language server, and the language server never for a run: they are two workers over the one compiled module.

The bundle is committed, with its source and its lock file, rather than built in the site image: building it needs npm and the registry, and the site image downloads nothing but the release; sh playground/editor/build.sh (npm ci --ignore-scripts, then esbuild) rebuilds it where the editor changes, the licenses of the fourteen packages it holds stand at its end, and CI's playground job checks that the committed file is what the source builds.

The gallery is playground/examples/: a file per example and an index.json of id, file, title, description, category, level, default and de (the German title and description), copied beside the toolchain by build.sh and into assets/examples/ by the site. /play opens the address's program (#code=), the example it names (#example=<id>), or the default example; Examples above the editor lists them by category in a panel (the overlay's shadow, rising 4 px, a sheet on a phone), in German on the German site; choosing one asks first only where the reader changed the code, and the address names the example until the code changes.

Measured under node 24 and in headless Chrome on a local server, on a machine running other gates: the language server answers initialize in about 90 ms after the module is compiled, checks the first document in 190 to 370 ms (it reads the standard library once), a keystroke's change and a completion after it in 50 to 150 ms, hover and semantic tokens in under 10 ms; the check of the workspace after initialized takes about 0.6 s once, in the background. On /play the editor replaces the light one about 0.1 s after the page loaded, and a typed error is underlined within a second (half of it the client's wait for the typing to stop). A run's first output is as fast as before: the run worker is untouched.

Monaco in every runnable block (2026-09-30)#

The owner's feedback on the live site a day later: the language server was on /play but not in the runnable blocks of the documentation, where it belongs as much; the hover and completion documentation of CodeMirror's client was badly laid out ("VS Code would do better"); and before its first click a block's text was larger than after it and sat on the bottom edge of its frame. The last had a cause of its own: the light editor's coloured copy carried the class code, so the rule of the front page's panels (.panel-code pre.code, 15 px on 24 px) sized it while the textarea over it kept 14 px on 21 px; the editor that replaced it had its own.

The editor is Monaco, the editor of VS Code, on /play and in every runnable block, with a bridge of its own to the language server. Its hover, completion and signature widgets render the server's Markdown the way VS Code renders it - the declaration a hover opens with coloured by the language's grammar, links, lists, code in a sentence - which is what the feedback asked for, and what CodeMirror's client would have had to be taught piece by piece.

• The bridge registers, for the language torbscript, completion (an item's signature and documentation resolved when it is shown, snippets, the documentation beside the list from the start), hover, signature help, definition within the document, rename with its check first, formatting, the quick fixes of a diagnostic, and semantic tokens, whose legend puts mutable first so the theme finds variable.mutable; the server's diagnostics become markers. Monaco renders the Markdown and sanitizes it: no HTML, and no link that runs a command. One language worker per page holds every block as a document, as before; a change is sent a quarter of a second after the last keystroke, or at once when a request needs it, as the whole text.
• A Monarch grammar (editor/grammar.mjs) colours the code before the server has checked it and the ```trb blocks of the documentation; it follows the extension's TextMate grammar, and the language configuration - comments, brackets, indentation - is the extension's file itself.
• The theme is read from the site's tokens on the page (editor/theme.mjs) whenever the site's theme changes, so the colours have one source; the widgets are raised surfaces with a hairline and the overlay's shadow, their prose in Chivo and their code in Geist Mono without ligatures and with the slashed zero, and the matched letters of completion are weight, not colour. Brackets keep the colour of punctuation, as on the site.
• The swap moves nothing. A block shows the site's highlighted code in a frame of exactly Monaco's metrics - taken from the pre the site wrote, so the front page's larger panels keep theirs - and Monaco starts with the site's colours as its first semantic tokens, until the language server's replace them. Measured in headless Chrome: the frame and the first character stay at the same pixel, in both themes, for a block of the documentation, a panel of the front page and /play with its line numbers.
• When it loads: the editor when the pointer comes over a block or the focus into it, so the first click already lands in Monaco; the 4 MB language worker at the first focus in the code, as before; on /play both at once. A device of touch alone ((hover: none) and (pointer: coarse)) keeps the light editor, without the language server, and never fetches the editor; a browser that cannot load it gets the light editor in its place.
• Built like the editor before it: playground/editor/package.json and its lock file (monaco-editor 0.57.0 and esbuild), build.mjs bundling only the contributions the playground uses into playground-editor.js, Monaco's stylesheet into playground-editor.css and its icon font as playground-codicon.ttf, all committed and rebuilt byte for byte by CI. Three changes to Monaco's sources are made on the way, each checked: the diff editors become empty classes (170 KB less), the warning of the editor worker's code running in the page is left out - the playground ships no editor worker; what it needs of one, the smallest edits of a formatting, is a moment's work in the page - and the font is added by the module with the build's ?v=, which the stylesheet cannot know. The site copies the two new files and hashes them into ?v=.

Measured in headless Chrome on a local server (gzip), on a machine running other work: the bundle is 3.31 MB, 849 KB gzipped, its stylesheet 19 KB and the font 75 KB, against CodeMirror's 452 KB and 142 KB; from the pointer entering a block to Monaco in its place 0.35 to 0.6 s the first time; the first completion in a block 0.9 s after the first click, the language worker's start and first check included; completion after a . in 0.2 to 0.3 s; a typed error marked 0.3 s after the keystroke.

/play is wide. The site's stylesheet gives the page the width of the screen up to 1840 px, the text around the tool keeping its measure; the tool is a toolbar - the gallery, Run, Format - above the editor and the output, which stand side by side from 1100 px, 3 to 2 and from 1700 px 7 to 4, as tall as the window. The gallery shows the categories as columns with a heading each - a marker in the category's colour, taken from the syntax colours in order and the brand's accent last, its name and its count - each example's title, its level as a small badge and its line of description, the open example marked by its category's colour; the panel has the brand's accent as its top rule.

The benchmarks page, as built (2026-09-30)#

Decided: the site shows how fast TorbScript is, measured by the forge every night (site/benchmarks.md). Six programs of the Computer Language Benchmarks Game are in benchmarks/game/, each in TorbScript and in the Benchmarks Game's own C, Python and JavaScript; benchmarks/game.sh builds and runs them all - TorbScript with torb build and in the VM - checks every output against the C's and writes one JSON report (benchmarks/README.md, "The Benchmarks Game").

nightly.yml ── publish ── images ── benchmarks.yml: game.sh with the nightly's torb ──► release `benchmarks`
                                                                                          benchmarks.json (newest)
Dockerfile.site: tools/fetch-benchmarks.sh ──► build/benchmarks.json ──► torb docs site   benchmarks-<version>.json

• Measured on the forge's runner, never on a developer's machine. The same machine every night, every language in the same run, the languages taking turns. A report from anywhere else can be rendered - torb docs site reads build/benchmarks.json or the file --benchmarks names - and the page then says it was not measured by the forge ("origin" is not ci).
• After the images. The runner runs two jobs at a time, and the image builds are hours of C compiles; measuring beside them would measure them too. So a nightly's site image, built before the measurement of its night, shows the report of the night before; the site of main (edge) fetches the newest when it is built.
• A release of its own, benchmarks, not an asset of the nightly. release-sync refuses a release with an asset its signed SHA256SUMS does not list (verifyHashes of tools/release-sync), and the report is written after the sums are signed. A prerelease without a version in its tag is never placed by release-sync, like seeds. The report of every night stays beside the newest, as benchmarks-<version>.json, for a history the page does not draw yet.
• Without a report the site is still whole. tools/fetch-benchmarks.sh exits 0 when there is nothing to fetch, and the page says that nothing is measured yet; a report that cannot be read is left out the same way. A report with fewer than C's and the native binary's times of every program is kept as the workflow's artifact and not published.
• What it measures, honestly. The Benchmarks Game's plain single-threaded programs (its #8 family), not its fastest; gcc -O2 against torb build in its release profile, the same compiler and optimization; the VM and Python on a smaller input than the binaries, each ratio against C on the same input; the VM as it is downloaded, a static musl binary. Where TorbScript is slower, the page says so and why - PERFORMANCE.md section 4.3 has the first numbers and the causes.
• Go and Rust are left out for now: the question the page answers is TorbScript against C and the VM against the interpreters people know, and each more toolchain is minutes of every night on the one runner.

Hosting#

Decision: every public URL is under torb.dev and packages.torb.dev, and the output is files; the provider behind them is replaceable without changing a single URL a script or a lock file contains.

• The site: static files from CI to a static host — GitHub Pages (the repository is there already, fact 17), Cloudflare Pages, Netlify, or a small server with Caddy. All four serve a directory; the one that is chosen is a question of price and taste, not of design.
• The downloads: release archives are large and many; they live in object storage or GitHub Releases, and torb.dev/download/<version>/<file> answers with them - a redirect while the repository is public and GitHub's own URL can be given out, and (decided 2026-09-25, section 7.11's "Public downloads while the repository is private") a synced copy on the server itself while it is not, since a private repository's release URL answers a login page to everyone else. Either way the install scripts and torb upgrade only ever see the torb.dev URL.
• .dev is on the HSTS preload list as a whole top-level domain, so every page is HTTPS or nothing; every host above handles the certificate.
• DNS and mail stay with the owner, not with the host: security@torb.dev (section 9) needs mail for the domain.

7. The registry#

Decision: packages.torb.dev is two things with one boundary. Reading is static files — a sparse index, immutable archives, generated documentation — behind a CDN, which any mirror can serve. Writing is one small service — accounts, owners, tokens, publish, yank — that is the only writer of those files. A client needs the service only to publish; it resolves, downloads and verifies from files.

7.1 Owners#

owner/name is decided (CONCEPT, PROJECT.md section 6: segment = lowercase (lowercase | digit | "-")*, a dotted owner reserved). An owner is a namespace on one registry, and a project binds an owner to a registry with registry "acme", url:; an owner that no project binds resolves at packages.torb.dev.

The account page is in the registry's shell (built 2026-10-10, #295): /account and the pages around it (sign in, sign up, claim, passkeys, authenticator app, step-up) are written by the write service through the same shell as the package pages - the header with the packages label, assets/site.css, assets/registry.css, the footer, the stored theme and the theme toggle of assets/registry.js - with the ink primary button, never a red one. Their Content-Security-Policy is default-src 'none'; script-src 'self'; style-src 'self'; font-src 'self'; img-src 'self'; form-action 'self'; frame-ancestors 'none'; base-uri 'none' (form-action also names a provider's authorization endpoint on a page with a button to it): the files of the host itself and nothing inline - no inline script, no style=, no handler, no unsafe-inline. The three pages that ask the browser for a passkey also load the one script /account/passkey.js, the same policy. Every page is still Cache-Control: no-store, escaped and CSRF-protected.

The "elsewhere" owner is the answer to dependency confusion that a registry can give. PROJECT.md's binding already prevents it where the line is written; an organisation that forgets the line in one project would otherwise fetch whatever a stranger published under its name. Claiming the owner publicly closes that gap for free.

As built (2026-10-12, #19): an owner member of an organisation - with the owners action and a Torb-Code like every owners call - or the operator names the registry with PUT /api/1/owners/<owner>/elsewhere {url} and takes it back with DELETE. The URL is https:// and a host name - no IP literal, no localhost, not the registry's own, no user, query or fragment, at most 200 bytes - kept in one form (the host in lower case, a name beyond ASCII as xn--, no port 443, no trailing /), and is only ever written and printed, never fetched, so it gives the registry no request to make. A person owner is a 400, an owner that has a package here (published, or reserved by its trusted publishers) a 409: a release is never moved (7.3). While the URL stands, a publish, a trusted-publishing exchange and a new package name of the owner are a 409 that names it and the registry "acme", url: ... line that binds it. The owner's file (7.4, 7.14) carries the URL, signed, so a mirror cannot invent one; the client prints it and never binds it by itself (#342, 7.13), because a stranger's claim must not rebind anyone's build.

As built (2026-10-13, #341): an owner member of an organisation - the same call class, Torb-Code and operator rule as above - proves a domain with PUT /api/1/owners/<owner>/domain {domain} and withdraws it with DELETE (the domain in the body too, since an organisation holds up to 5). The record is a TXT record at _torb.<domain> with one string torb-owner=<owner>: the owner's name binds it to one owner, and only whoever controls the domain's DNS can add it, so no nonce is asked for. Any string of any TXT record of the name counts, so the record can sit beside others. The registry looks it up in the request, through the std/network resolver (the system's name servers, or the REGISTRY_DNS_SERVERS it is given) with the resolver's own timeouts, at most 2 lookups at a time and outside the write lock; it stores nothing unless the record is there, and the 422 says which of four things it met: no such name, no TXT record, a record that names another owner, or a failed lookup. The domain is a domain name in lower case, a name beyond ASCII as xn--, with at least two labels, no IP address and at most 253 bytes (400); one owner holds a domain (409 for another's), and an organisation at most 5. Held domains go into domain: of the owner's file, sorted and separated by spaces, so the signed format is the one of #19 and its changed grows with each change, and the package page of every package of the owner shows verified: <domain> in its head.

As built (2026-10-13, #343): a domain can be lost or sold, so the registry checks every verified domain again once a day, with the same lookup and the same limit of 2 at once, from a task of the service beside the documentation worker. Each domain's day starts at the time of day it was verified, so the lookups spread over the day, and one not checked for a day - the registry was down - is checked at start; two checks are at least half a day apart. A lookup that is answered without the record (no such name, no TXT record, only other owners') counts a missing day; one that gets no answer (a timeout, SERVFAIL) counts nothing, because an outage of a provider is no loss of the domain, and a check that finds the record sets the count back. The third missing day in a row withdraws the domain: its row goes, the owner's file and package pages are written again without it, the audit log gets domain-withdrawn by registry, and the domain can be claimed again at once. domains keeps checked and failures for it; a database from before gets both, as checked when it was verified.

Names that would confuse are refused at creation, for owners and for package names: equal after removing hyphens (acme-corp against acmecorp, which is JSR's rule), within one edit of an owner or a package with many dependents, or one of the pairs ASCII cannot tell apart at a glance (l/1, o/0, rn/m). The segment grammar already rules out every Unicode confusable. A refusal names the existing owner, and the moderators can grant the name by hand.

7.2 Publishing#

What is uploaded: source, and only source. An archive holds the package's files by PROJECT.md section 3's rule — every .trb below the package directory that is not inside a nested package, skipping hidden directories, build, target and node_modules — plus the resource files its code names (RESOURCES.md), project.trb, project.lock.trb with its settings section and its graph as information, README.md and the license files. No include or exclude list: it would be a second source of truth about which files a package has, which is the disease PROJECT.md section 1 lists. No binaries, no generated C, and no C at all until foreign is decided (section 2; open, see FOREIGN.md section 5.3).

The archive is a deterministic tar.gz; the identity is the hash of the tree. Entries sorted, timestamps zero, modes fixed, owner empty. The hash the lock pins is not the hash of the archive's bytes but sha256: over a canonical listing of every file's path and SHA-256 — Go's h1: directory hash — so a mirror may recompress, an archive: source (PROJECT.md section 7) is verified the same way, and a change of compression level never changes a lock file.

$ torb publish --dry-run
acme/http 1.2.5
  read by project.trb:  file VERSION, variable CI_COMMIT_TAG
  checked:              7 files, no problems (every target)
  capabilities:         network (src/client.trb), environment (src/proxy.trb)
  files:                14, 38 KB, archive 11 KB
  hash:                 sha256:6f1c...
nothing was uploaded (--dry-run)

torb publish, in order:

1. Read the static subset, and refuse without name, version, description or license (PROJECT.md section 10: "required to publish").
2. Evaluate project.trb in the sandbox, write the settings section of project.lock.trb, and read it back with the static reader — a setting that does not survive being printed is a refusal (PROJECT.md section 8).
3. Print the environment variables the manifest read, by name, which is PROJECT.md's first pitfall made visible.
4. torb check --every-target of the package against its locked graph: a package that does not check, or does not lower on a target, is refused locally, like cargo publish's verification build — except that nothing is built and nothing runs.
5. Collect the files, refuse when the code names a resource the archive does not contain, write the archive, compute the hash. --dry-run stops here and prints the summary above.
6. Upload with a token (section 7.6).

The registry, on receipt, trusts nothing the client computed: it checks that the token may publish this owner/name, that the version is new, that the archive has the shape above and is within the size limit, re-reads the lock's settings statically — it never evaluates a project.trb — recomputes the hash, and re-derives the capabilities from the imports (section 7.8). It then appends the release to the index, signs it, stores the archive and queues the documentation (section 7.7). The server does not refuse a package that fails to check on its side: its toolchain may be a different patch release, and a checker bug on the server must not block a publisher. It shows the result instead.

Trusted publishing: a CI job publishes without a stored token, with a short-lived one exchanged for the CI system's OIDC identity (crates.io, npm, PyPI and JSR all do this since 2023-2025). An owner can require it and switch tokens off for a package.

7.3 Immutability and yanking#

• A published version is never replaced and never deleted (CONCEPT: "A version can be withdrawn for new resolutions, never replaced or deleted"). There is no revert window — Hex allows one of an hour, npm 72 hours; a mistake is fixed by the next patch, and --dry-run is where a mistake is caught.
• torb yank acme/http 1.2.4 --reason "..." withdraws a version for new resolutions. A lock that already pins it keeps building, and prints the reason once per build. --undo reverses a yank.
• The one exception is removal by the moderators, for malware or a legal order. The index keeps a tombstone line with the reason, the archive is gone, and a lock that pins the hash fails with that reason instead of a download error.
• Deprecating a whole package (torb deprecate acme/http --use acme/http2 --reason "...") is a flag on the package, shown by torb add for the packages named on its command line and, once the page exists, on the page; it withdraws nothing, every version resolves as before, and --undo takes the flag back. A member with the yank action may (built 2026-10-10, sections 7.4 and 7.13).

7.4 The index and the API#

Decision: a sparse index of static files, one per package, in TorbScript, append-only. A value is its constructor call (ENCODING.md), the lock file is a receiver script of literals (PROJECT.md section 8), and the index is the same kind of file: the static reader reads it, nothing evaluates it.

https://packages.torb.dev/index/config.trb            the registry's settings and its public keys
https://packages.torb.dev/index/<owner>/<name>.trb     one file per package, append-only
https://packages.torb.dev/index/<owner>/owner.trb      the owner: kind, verified domain, or "elsewhere"
https://packages.torb.dev/archives/<owner>/<name>/<version>.tar.gz
https://packages.torb.dev/api/1/...                    publish, yank, owners, tokens, search

// index/acme/http.trb - written by packages.torb.dev. Lines are only ever appended.

package "acme/http"

release "1.2.4" {
  hash "sha256:0b7e..."
  language "0.4.0"
  dependencies {
    runtime "acme/json:^2.0.0"
  }
  capabilities "network"
  signature "ed25519:..."
}

release "1.2.5" {
  hash "sha256:6f1c..."
  language "0.4.0"
  dependencies {
    runtime "acme/json:^2.0.1"
  }
  capabilities "network", "environment"
  signature "ed25519:..."
}

yank "1.2.4", reason: "sends the proxy password in clear text", signature: "ed25519:..."

deprecate "acme/http", use: "acme/http2", reason: "http2 keeps the API", signature: "ed25519:..."

The client reads exactly this format since 2026-09-26; what this section left open is decided in section 7.13.

• A deprecation is a line of the package, not of a version: deprecate "<package>", use: "...", reason: "...", signature: "..." (use and reason are optional) and undeprecate "<package>", signature: "...". The package is the file's own, or the file is refused; the last of the two lines holds, and a second deprecate replaces the notice of the first. The index stays append-only. A reader from before the lines skips them as unknown words and verifies the rest (section 7.14, "the position").

• Only what resolution needs is in the index: the version, the hash, the language minimum, the runtime dependencies and the capabilities — the last so that torb add and torb update can show "this update gains the network" (CONCEPT) before downloading anything. Description, keywords, the README and the documentation are on the API and the page.

• Append-only, and the yank is a new line rather than an edited field (crates.io edits yanked in place): a client or a mirror that has a prefix of the file fetches the rest with an HTTP range request, and the file can be cached by the CDN with a short lifetime and validated with ETag.

• The owner directory is the fan-out: owner/name already spreads the files, so crates.io's prefix directories (ca/rg/cargo) are not needed.

• Every record is signed by the registry's key (Ed25519), whose public half ships in torb and is listed in config.trb with its successor for rotation. Hex signs its registry the same way. It is what makes a mirror untrusted: a mirror can withhold a release, but it cannot change one. Built on 2026-09-27; section 7.14 decides what this left open.

7.5 Mirrors, vendoring and offline#

• A mirror is a directory of the same files, named in the user's own configuration (~/.torb/config.trb, mirror "https://packages.internal.test") and never in a project: where a build machine downloads from is the machine's business, and the lock pins hashes and signatures, not URLs. Built 2026-10-09 (compiler/src/package/user-config.trb, docs/tooling/config-trb.md):
  • The file is $TORB_CONFIG, else <torb home>/config.trb, and no file is no mirror. It is a receiver script of literal mirror "<url>" lines, read statically. A line that is anything else, a URL that is neither https:, http: nor file: and a directory, and a mirror named twice are errors at their line. A relative file: path is relative to the directory of config.trb.
  • A registry on the network is asked through its mirrors in the order of the file, and at its own URL last. A file: registry is never mirrored, and torb publish never goes through a mirror.
  • A 404 or 410, a file: mirror without the file, or a mirror that cannot be reached passes the request on to the next source, and the first answer wins. Where no source has a file and one could not be reached, the error names every source.
  • Trust never comes from a mirror. A mirror's index/config.trb is checked against the keys shipped or pinned for the registry. The keys of a registry with neither are fetched from the registry itself, so the first contact that pins them never goes through a mirror. A changed or unsigned record, or an archive of another tree hash, from a mirror is refused naming the mirror, and nothing it served is written into the cache.
  • The lock names the registry, so a lock written through a mirror is byte for byte the one written without it. The cache keeps an index copy under the registry, whichever source served it, and --offline contacts no mirror.
• The cache is content-addressed: ~/.torb/cache/<hash>/, verified on every extraction, shared by every project.
• --offline resolves from the cache and the lock only, and fails naming the first package it would have to fetch.
• torb vendor copies the locked graph into vendor/ and writes a source ... path: line per package, which is PROJECT.md's own mechanism rather than a new one.
  • As built (compiler/src/package/vendor.trb, docs/tooling/torb-vendor.md): vendor/<owner>/<name>/ holds the package as the cache unpacks it, and every tree hash is checked, from the cache or from the registry, before the first file is written. A second run changes nothing, and a package that left the graph leaves vendor/ and project.trb. The lock lists a copy as a path: package, which nothing hashes afterwards, and torb publish refuses a project that depends on one. tools/vendor.sh builds the project with an empty cache.

7.6 Security#

The advisory database is a public repository of TorbScript files, one per advisory, reviewed by pull request, with an export in the OSV schema so that osv.dev and the scanners that read it see TorbScript packages too.

The advisory file, as built (2026-10-24, #451). The file format and the local reader exist; the public repository, the endpoint that serves it and the OSV export do not (steps of #309 that wait for the owner). A database is a directory, and an advisory is one file in it, <directory>/<owner>/<name>/<id>.trb, so a package's advisories are found by its name without opening the rest. <id> is TORB-<year>-<number> (four digits, then four or more). The file is a receiver script of literals, read statically with the reader of the index and the lock (7.4, 7.14): nothing is evaluated.

advisory "TORB-2026-0001"
package "acme/http"
summary "sends the proxy password in clear text"
severity "high"
affected ">=1.0.0 <1.2.5", ">=2.0.0 <2.1.1"
published 1760000000
aliases "CVE-2026-12345"
references "https://example.test/advisory"

A file is refused, never skipped, where a word is none of these, a word is written twice or takes anything but plain texts, a required word is missing, advisory or package disagrees with the path, severity is not one of the four, an affected text is no requirement, or published is no number: a database is read whole or not at all, and a typo must not turn into "no findings". A directory of a package holds nothing but <id>.trb files. There is no signature in this step: the directory is the reviewed repository, and pull request review is the trust. Whether a copy served by a registry is signed like the index (7.14) is decided with the endpoint.

torb audit --advisories <directory> (docs/tooling/torb-audit.md) reads the advisories of every locked registry package, a path: package skipped, and reports each one that covers the pinned version, ordered by package and then by id; a directory that does not exist or an advisory file that is refused is exit 2, because a database that cannot be read must not look like a clean lock. Without the flag nothing changes. Code: compiler/src/package/advisory.trb.

7.7 Documentation per package#

packages.torb.dev/<owner>/<name>/<version>/docs is torb doc of that version, generated by the registry with the toolchain the package's language line names, rendered by the same site generator as torb.dev. Generating it runs none of the package's code: torb doc parses and checks; the # Examples of a doc comment are type checked, not run (torb doc --check --no-run; the doc tests that run them are the author's torb doc --check), and a constant is evaluated by the checker's operator folding and nothing else (CONCEPT: "No function calls and no native calls"). That is a difference from docs.rs, which has to sandbox a build because building a crate runs its build script and its procedural macros. The worker still runs under time and memory limits, because a pathological input is a denial of service even when it is not code.

As built (2026-10-09): the worker is a task of the write service (tools/registry/src/documentation.trb) and renders with the registry's own toolchain, the newest it has, not one per language line: a package whose line asks for a newer language than that toolchain's waits, pending, and is looked at again daily and at every start. The pages are at packages.torb.dev/docs/<owner>/<name>/<version>/. A publish queues the version in a documentation table of the database; the worker unpacks the archive and every locked dependency from the registry's own storage, each against the hash its lock names, refuses a path: dependency and a project.trb that names another package, and runs torb doc --check --no-run, then torb doc --output --escape-html, under timeout and prlimit (120 s, 1 GiB, 50 MiB of output and 512 processes by default, REGISTRY_DOC_*) with an empty environment, inside bubblewrap (REGISTRY_DOC_ISOLATION, bwrap by default): new user, pid, ipc, uts, network and cgroup namespaces, the user 65534, /usr, the system's bin and lib* and the toolchain's directory read-only, an empty /tmp, and the scratch directory as the one writable path, so a render sees none of the service's files or environment and has no network. The worker refuses to start where the --version probe fails inside bubblewrap, and where its scratch directory lies inside the storage or the database; none exists for the tests' stand-in toolchain and for development. Whether the container may create the namespaces is step 2 of #233 (the deployment). The image ships with the worker off (REGISTRY_DOC_TORB empty): an image pull alone does not start it, the operator opts in. A package that does not check is failed at once with what torb check says and gets no pages; any other failure is tried again three times, after 1, 5 and 25 minutes, and is then failed: torb doc ends with 0 where it rendered, 1 where it found a problem in the package, and 74 (EX_IOERR) where it failed on the disk - a full disk, an output it cannot write, a file it cannot read -, and only 1 is the package's. The worker records its toolchain as the first line of torb --version, a +, and the first 12 hex digits of the SHA-256 of the executable, so that the start of a worker with another build of the same version queues the failed versions again. The state and the problem are GET /api/1/packages/<owner>/<name>/<version>/docs, and the operator queues a version again with POST on the same path. nginx serves the pages with a Content-Security-Policy that runs only the host's own scripts, since their doc comments are a stranger's text, and --escape-html keeps that text from becoming markup in the first place: the raw HTML of a comment is written as text and a link to a script as an empty one. The flag is part of the worker's command line, not a setting, and it fails closed: a toolchain that does not know it refuses the command ("not a flag of this command"), so the version is failed instead of served unescaped.

7.8 The capability summary#

CONCEPT's promise — "the compiler knows from the imports alone what a package can touch" — becomes a line on every package page, and it is the registry's selling point that no other registry in section 7.12 can offer, because none of their languages can make it.

acme/http 1.2.5
  touches   network      src/client.trb, src/pool.trb
            environment  src/proxy.trb
  through   acme/json    nothing
  gained since 1.2.4:    environment

• The table of capabilities lives in std: one list that says which package is which capability — files (std/fs), network (std/http, later std/net), processes (std/process), environment (std/environment), clock (Clock of std/time), entropy (Entropy of std/os/entropy), the operating system (std/os), loading scripts (std/sandbox), foreign functions (foreign). A std package that is not on the list is pure, and a test asserts that every std package with a native that reaches the machine is on it. A capability is a reading, not a type: the values a capability package answers in (Timestamp of std/time, OsError of std/os) are pure, so the summary decides by each imported name, and a package with a Timestamp in a signature touches no clock.
• Direct and transitive are shown apart. What a package's own modules import is a fact of the archive; what it reaches through its dependencies depends on the resolution, so the page shows it for the graph the package was published with and says so.
• The lock records the capabilities of the whole graph (CONCEPT), and torb update asks before taking a version that gains one.
• Built per version (2026-10-23, #51): torb publish prints the summary of a package's own imports, the registry derives it again from the archive, writes it into the release row (releases.capabilities, comma-joined, empty for none) and the package page's table of versions shows it per version. A version whose set has a capability the nearest earlier version nobody yanked lacks reads gained: <names>; the first version, a version that lost one and a version beside a release that recorded nothing carry no flag. A release published before the column existed is not recorded, never none: that would be a claim nobody checked, on a security display. The table of modules and pure names is the page docs/tooling/package-capabilities.md, and a registry test keeps it in step with capabilityOf. Open: the table in std itself, with the test that every std package that reaches the machine is on it, and the transitive view ("through ...", which needs the resolved graph).

7.9 Search and ranking#

Search covers owner, name, description and keywords, which the vocabulary does not have yet: keywords is added (not static, in the lock's settings, required by nothing). Ranking after text relevance: the number of packages that depend on it (downloads are counted and shown, but not ranked on, because they are cheap to inflate), then the package checks the registry computed — documented public declarations (torb docs source --statistics counts them already), it checks and lowers on every target, it has a README and a license. The checks are shown as a list, not as a score out of a hundred.

Built 2026-10-09 (tools/registry/src/search.trb): keywords "http", "client" is a setting of std/project, at most five words of 2 to 24 characters of a-z, 0-9 and -, checked by torb publish and by the registry with the same publishProblems. GET /api/1/search?q=<text>&limit=<1..50>&offset=<n> is public and answers {query, total, limit, offset, packages}, each package with its latest release nobody yanked (the highest stable one, else the highest pre-release), description, keywords, capabilities, dependents and publish time. A query is at most 8 terms of at most 64 characters, split at whitespace and lower-cased, and a package matches every term; a term scores the best of the name exactly 16, a prefix of it 8, inside it 4, a keyword 4, the owner 2, the description 1 (a term with a / is matched against owner/name), and the packages are ordered by the sum, then by how many packages' latest releases depend on them at runtime, then by the newest publish. The rows are a derived table rewritten in the batch that records a publish, a yank or an unyank, and filled at start where a package has none; the index stays the truth. A scan with instr, not FTS5, since the sqlite3 shell's build options are the container's. Ranking on the package checks waits until the registry computes them.

7.10 Moderation and policies#

Written before the launch and linked from every page:

• Names: first come; squatting (a name held without a package) is removed on request after an attempt to reach the holder; there are no transfers of an abandoned name except by its owner, because a transferred name is a supply-chain attack waiting for a victim.
• Content: malware, stolen code and illegal content are removed (7.3); everything else is the author's.
• Limits: an archive of at most 10 MB (crates.io's number), a rate limit on publishing per owner, both raised by request.
• Disputes and reports: an address on the site, an answer within a stated time, and a public log of removals with their reason.

7.11 Hosting and the server#

Decided (2026-09-25): the registry starts on the project's own server. A root server with Docker and Traefik runs three containers behind one TLS proxy:

Traefik (TLS, Let's Encrypt)
 ├─ packages.torb.dev/index, /archives, /packages, /docs  ->  a static file server over /srv/torb/registry
 ├─ packages.torb.dev/api                      ->  the write service (TorbScript, SQLite)
 └─ torb.dev                                   ->  the website, install.sh and install.ps1;
                                                    /download/<version>/<file> served from /srv/torb/download,
                                                    written by release-sync (below) - not a redirect to GitHub

• The package pages are static files too (built 2026-10-10, #12): packages/<owner>/<name>/index.html below the same storage, one per package, which the write service writes from its database - never a request of a reader. They are rewritten under the write lock after a publish, a yank and an unyank (and the pages of the packages whose count of dependents the change moved), and rewritten by the documentation worker once a version is rendered, which is when a page links its documentation. At every start fillPages compares the stored page of each package with the one the database makes now and rewrites every page that differs (a missing one is written, an equal one is left alone), so a registry of a newer toolchain brings its shell to the pages already in the storage, with no marker in them. The shell around a page is compiler/src/documentation/site-registry.trb: the site's header with the label packages and the search field (a plain form that sends q to /search/, see the next bullet), the brand's tokens, and assets/site.css, assets/registry.css and assets/registry.js, which the registry host serves from the image's site root beside its own files. A page carries text strangers wrote (a description, a keyword, the reason of a yank), so every stored value is escaped, the page has no inline script or style, and the host answers it under script-src 'self'. A page shows the name, the latest version nobody yanked, the description, the keywords and capabilities as chips, the command that adds it with a copy button, its runtime dependencies, its count of dependents, the publish date, a link to the documentation where it is rendered, and a table of every version with the capabilities of that version (7.8, #51) where a yanked one has the warning tint, the word and its reason; a package with every release yanked keeps its page, with a notice. The account pages the write service renders itself wear the same shell under a policy of the host's own files (section 7.1, #295).
• The search page is a static file too (built 2026-10-10, #241): search/index.html below the same storage, shown at https://packages.torb.dev/search/. Unlike a package page, which is derived from the database and written where it differs from the stored one, the write service writes it at every start and overwrites what is there, so a registry of a newer toolchain brings its shell with it. It is the shell with a plain <form method="get" action="/search/"> (the field q) and empty places for a status line, the results and the links to the previous and next page; it holds no result. The script, assets/registry-search.js (written by torb docs site beside registry.js, and loaded by this page alone), reads q and offset from the address, asks GET /api/1/search of the same origin once (20 packages a page) and renders the answer with createElement and textContent only: the name, version, description, keywords and capabilities as chips and the count of dependents, each result linking to /packages/<owner>/<name>/ where the owner and the name have the shape of a name, and shown as plain text where they do not. The states of an empty query, a search that finds nothing, a refused query (the API's message and problems, as text) and an API that does not answer (a sentence and a link to the API) each have their text, and a reader without the script reads a note that names the API. The host answers /search/ under the policy of the package pages, so the page has no inline script, no style= and no handler. The capability summary is built per version (section 7.8, #51); the transitive view over the dependency graph is not.
• A CDN in front caches an archive as immutable for a year and an index file briefly with an ETag, so the server's bandwidth and a traffic spike are the CDN's problem, not the registry's.
• Backups off the server: the database continuously (Litestream), the files nightly (restic), both to object storage at another provider; and every index file is mirrored into a public git repository, which doubles as a readable log of every release ever published.
• The write service stores through the storage layer of docs/design/URI.md section 11 - file: at launch, s3: when the registry outgrows one disk - so moving the files is a change of configuration, and no URL a lock file or a script contains changes. The registry is the first real user of that driver layer.
• Not a git repository for the archives, and not a container registry: git grows with every binary and crates.io left its git index for the sparse one because clones grew too large; an OCI registry needs a token dance per anonymous download and breaks "a mirror is a directory of the same files" (section 7.5).

The write service is written in TorbScript, as the first real server program of the language — which needs the HTTP server of milestone 10 (docs/ROADMAP.md orders std/net, then std/http, early in 10), TLS terminated by the proxy in front of it, and a database. That puts the registry launch after the first part of milestone 10; question 2 of section 12 is whether to accept a server in another language to open earlier. It is built (2026-09-27, "The root server and the write service, as built" below): std/http's server had landed, and TorbScript it is.

Public downloads while the repository is private (decided here)#

The repository is private today (fact 3), but section 5's installers and torb upgrade have to work now, from a public URL, without a token. A plain redirect to a GitHub release (the diagram above, before this decision) answers a login page to anyone who is not a collaborator - the site would work for the maintainer and nobody else. Three ways to close that gap:

tools/release-sync is that pull: a TorbScript program (std/http for both the webhook server and the forge's API client, std/json for the payload and the API's response), built and run as its own container (tools/deploy/Dockerfile.release-sync). Since 2026-09-27 it pulls from the forge, Forgejo at git.torb.dev (section 14), and from GitHub only where RELEASE_SYNC_FORGE=github says so; the two differ in four places, which are the members of Forge in tools/release-sync/src/forge.trb. It:

1. Listens on /webhook for the forge's "release published" event, its signature checked - X-Forgejo-Signature, the bare hex of the HMAC-SHA256 over the raw body, or GitHub's X-Hub-Signature-256, sha256=<hex>, which Forgejo sends as well - computed by shelling out to openssl dgst -sha256 -hmac and compared without stopping at the first digit that differs, against a secret only this service and the webhook's configuration know. It answers 202 at once and syncs in a task of its own: the forge gives a delivery seconds, a download takes longer.
2. Never trusts the webhook's own asset list: it re-fetches the release from the API (GET /api/v1/repos/<owner>/<name>/releases/tags/<tag> on Forgejo, /repos/... on GitHub), with a read-only token only while the repository is private. The workflows publish a release as a draft first and make it public once its last asset is uploaded, which is when the forge sends "published" - measured on Forgejo 16.0.5: creating the draft and uploading send nothing. The forge does not deliver a failed webhook again, so a periodic check - at the start and every RELEASE_SYNC_POLL_SECONDS, default 300 - lists the newest releases (.../releases?draft=false&limit=50, ?per_page=50 on GitHub) and syncs every one that is not placed yet of the newest stable release, the newest preview (since 2026-09-29) and the nightlies of the thirty days ending with the newest one listed, the thirty days a nightly is kept (section 5, "Channels"). Until 2026-09-28 it asked .../releases/latest, which is stable releases only and a 404 while there is none: a nightly whose delivery was lost - the first production run lost one while the container was still starting and Traefik had no route to it - was never placed, and the check logged an error every five minutes.
3. Downloads every asset into a directory of its own below the scratch directory (curl: Forgejo's browser_download_url, GitHub's asset API URL with Accept: application/octet-stream), readable by its owner alone, verifies every archive against SHA256SUMS (std/digest over the file's chunks) and verifies SHA256SUMS.sig with cosign verify-blob --key against the project's public key, mounted at /etc/release-sync/cosign.pub (section 13, "Signing"; a release of GitHub: SHA256SUMS.sigstore.json against the identity of the workflow that made it) - refusing when cosign or the key is not on the machine at all, the same as a signature that does not verify: a release this program cannot check is not placed as if it had been. The scratch directory is <root>/download/.incoming (RELEASE_SYNC_SCRATCH): it has to be on the file system of <root>/download/ for step 4's rename, and the site never serves a hidden entry there. It was the container's own /tmp until the first production run found the rename into the mounted download directory failing with Invalid cross-device link; a scratch directory on another file system now fails with a message that names the variable.
4. Only then renames the whole verified directory to <root>/download/<version> in one step (File.rename), so a directory under a version's name is always complete - the same first run left an empty one behind, which the check, asking only whether the directory existed, took for placed. It then rewrites <root>/download/versions.txt whole or not at all (File.writeTextAtomically; that version's old line, if any, replaced; each channel newest first - stable, then preview, then nightly - since the installers take the first line of their channel) and, where the release is the newest stable one, repoints the <root>/download/latest symlink - a new link beside it renamed over the old one, so latest is never missing, which ln -sfn could not promise. A placement that fails after the rename is undone, the old directory and versions.txt put back, so the check tries it again; a version counts as placed once <root>/download/<version>/SHA256SUMS is there. A preview and a nightly have no "latest"; the nightly has /docs/nightly/ on the site (section 6), which this program does not touch. tools/release-sync/README.md has the variables, the webhook's answers and how to run it locally. Why curl and not std/http's body all the way to disk: the download is the one step left outside the language, and File.write(path, response.body) is its replacement once std/http's client follows the redirects GitHub answers an asset with. Hashing, moving and linking moved into std/digest and std/fs on 2026-09-27, when std/fs gained rename, symbolic links and the atomic replacement; before that they shelled out to sha256sum, mv and ln. curl and cosign are exactly the tools tools/fetch-seed.sh already assumes exist on every target, so release-sync's one target (its own container) is not a new assumption.

Tested: tools/release-sync/tests covers the pure decisions - which webhook actions to act on, which signature a request claims and whether it matches, reading a hash out of SHA256SUMS, the release JSON of both forges, the addresses and headers each is asked with, which releases the periodic check places, the order of versions.txt - as ordinary TorbScript tests; tests/check.test.trb the periodic check against a fake forge over loopback, and tests/place.test.trb the placement, the placements that fail and are undone, and the hashing in a temporary directory. The whole program ran once against a Forgejo 16.0.5 in a local container (2026-09-27): a release published the way release.yml publishes one, with SHA256SUMS signed by a throwaway cosign key, was placed through the webhook, with versions.txt and latest; a release whose archive did not match SHA256SUMS and one whose signature did not match were refused and placed nothing.

The root server and the write service, as built (2026-09-27)#

Decided by the owner (2026-09-27): the root server runs behind his existing Traefik, from ready-made images he pulls from a registry - GHCR when this was built, the forge's own cr.torb.dev since the same day's move (section 14), in the compose stack that runs the forge or beside it. Nothing is built on the server and nothing in the deployment opens a port or asks for a certificate: the containers join Traefik's network and claim their host and path with labels.

existing Traefik (TLS, Let's Encrypt; its network, entrypoint and resolver named in .env)
 ├─ torb.dev, www.torb.dev          ->  cr.torb.dev/torbscript/site      install.sh, install.ps1, /docs/<version>/reference,
 │                                                                       /download/... from /srv/torb/download (read-only)
 ├─ torb.dev/webhook                ->  cr.torb.dev/torbscript/release-sync writes /srv/torb/download
 ├─ packages.torb.dev               ->  cr.torb.dev/torbscript/site      /index, /archives, /docs from /srv/torb/registry (read-only)
 └─ packages.torb.dev/api           ->  cr.torb.dev/torbscript/registry  writes /srv/torb/registry, /srv/torb/database, the mirror
    litestream (sidecar)                  /srv/torb/database/registry.db -> object storage, continuously
    backup (restic, host cron)            /srv/torb/{registry,download,index-mirror} -> object storage, nightly

The images are built by .forgejo/workflows/images.yml, which release.yml calls once a release is published (tags <version> and latest) and nightly.yml once a nightly is (tags nightly-YYYYMMDD and nightly), and which runs by hand for a published release - and, since 2026-09-29, on every push to main that changes the site, for the site alone (tags edge and main-<commit>-<time>, "The site of main, as built" below): three images, pushed to cr.torb.dev/torbscript/ with the token of the Authorized Integration torbscript-images as the password of docker login (section 14), with the OCI labels source, revision, version, licenses (MIT) and url, and signed with cosign sign --key, the project's key (section 13, "Signing"). They are linux/amd64; linux/arm64 joins once a release carries a linux-arm64 toolchain - the build stage runs the toolchain of the image's own architecture - and QEMU registers in the runner's Docker, which the workflow tries and reports. The images are public, so the server pulls them without a login:

cosign verify --key https://git.torb.dev/torbscript/language/raw/branch/main/tools/deploy/cosign.pub \
  --insecure-ignore-tlog=true cr.torb.dev/torbscript/registry:0.2.0

tools/deploy/compose.example.yml (copied to compose.yml, never docker-compose.yml) runs site, release-sync, registry, the litestream sidecar and a backup service in the profile backup. No Traefik service: the external network is TRAEFIK_NETWORK (default traefik), and the routers' entrypoint and certificate resolver are TRAEFIK_ENTRYPOINT and TRAEFIK_CERTRESOLVER from .env (.env.example lists every variable). The data lives in TORB_DATA (default /srv/torb) as bind mounts: download/, registry/, database/, index-mirror/, each with exactly one writer. Litestream (litestream.yml) replicates the SQLite database to S3-compatible storage at another provider within seconds, with a daily snapshot kept 30 days; restic (backup.sh, run by the host's cron through docker compose --profile backup run --rm backup) backs up the files nightly to the same storage - the database is left out, a copy of a SQLite file being written is not a database - keeps 14 daily, 8 weekly and 12 monthly snapshots, and reads a thirtieth of the repository back every night.

The write service, tools/registry (its README lists the API and the variables):

The client: torb publish to an https:// registry uploads with curl (else wget) and prints the registry's answer. The token is TORB_TOKEN; without it, in a GitHub Actions job with id-token: write, the job's OIDC token is requested with the registry's host as audience and exchanged for the short-lived one (compiler/src/package/upload.trb, docs/tooling/torb-publish.md) - and the same in a Forgejo Actions job with enable-openid-connect: true, whose token endpoint answers the same request.

Tested: tools/registry/tests - RSA and JWT verification against a key and tokens made with Node's crypto, the name and scope rules, every API call over loopback with a database and a file: storage in a temporary directory (once as it works, once as it is refused), and torb publish driven against it; since 2026-09-27 also a Forgejo Actions token of a second key, its issuer's discovery document and key set served over loopback, and the refusals a Forgejo publisher has that a GitHub one has not; 75 tests, natively and in the VM, with sqlite3 on the PATH. The three images were built locally for linux/amd64 from a dist directory made the way the release makes it (a Linux torb compiled from the fixpoint's program.c, the toolchain laid out, the source packed): the registry's container answered, created an account and took a torb publish from the Windows host, writing the index, the archive and a WAL-mode database; the site served install.sh and the reference read-only, split by host name. linux/arm64 has not been built outside CI. Since 2026-09-28 the release binary's smoke test writes the registry's C before a release or a nightly is published (section 14, "What the first nightly reported").

Not built yet: signing up through a passkey (signing in through one, and through GitHub, GitLab and Codeberg, is built), asking for the second factor at sign-in (a TOTP app, recovery codes and the factor before publishing tokens are built), ranking on package checks (search is built, 7.9), the similarity rule against packages with many dependents, and an s3: driver. torb yank, owner and login speak to the API since 2026-10-09 (section 7.13), and torb reads an owner's file and prints an "elsewhere" owner since 2026-10-13 (section 7.13).

What the owner sets up once is docs/contributing/releasing.md, "The root server": DNS, the .env and cosign.pub, the forge's webhook, the first account, trusted publishers, the index mirror and the backup storage.

The site of main, as built (2026-09-29)#

Decided by the owner (2026-09-29): a change to the website reaches torb.dev fast, from main, without a nightly. Until then a change to docs/, the playground or its editor was on the server only after a nightly (every gate of every target, 15 to 30 minutes on the forge's one runner and up to an hour), a run of images.yml by hand, and a pull request to the infrastructure that pinned the new digests. The root server moves to k3s with Flux, which follows a tag of a registry by itself; what the repository owes it is an image of the site that follows main. Built on the same day: every push to main that changes what the site is built from builds cr.torb.dev/torbscript/site from that commit and pushes it as

never as latest, nightly or preview, signed with the project's key over the digest both tags name, and with the labels of the other images (source, revision, version - the main-... tag -, licenses, url).

Expected minutes, from the push to the pushed image, measured from the forge's runs of 2026-09-29: the bootstrap takes 4 to 6 minutes alone (compiling the seed 3, the seed building the compiler about 2 with mbedTLS, the compiler building itself under 1) and 9 to 13 beside a second one; compiling the playground 80 seconds in the image job and 90 to 155 in the gates; torb docs site and torb doc std 24 seconds; checkout, caches, the context, the push and the signature about half a minute more.

The job waits for one of the runner's two slots first: seconds, since ci.yml's first two jobs are short - longer only while a nightly or a release holds both. Flux's own interval comes on top.

Flux follows the image by itself: an ImageRepository of cr.torb.dev/torbscript/site (public, no secret) and an ImagePolicy whose filterTags pattern ^main-[0-9a-f]{8}-(?P<time>[0-9]+)$ extracts $time, with the policy numerical, ascending; an ImageUpdateAutomation with the setters strategy writes the newer tag into the manifest, and rolling back is pinning an older tag. docs/contributing/releasing.md, "The site of main", has the resources. Following edge by its digest (filterTags ^edge$, digestReflectionPolicy: Always with an interval) works too, and says less: the tag never names the commit that runs. Setting up Flux is the owner's.

Tested (2026-09-29): the workflows pass forgejo-runner validate (runner 13.2.0). On a local Forgejo 16.0.5, a push of the change started images.yml with the three image jobs skipped by the server and edge waiting; a push that touched only compiler/src/cli started none; the next push of docs/ cancelled the waiting run, and a run by hand with the channel edge cancelled that one, while a run by hand of the channel nightly ran beside it with edge skipped; images.yml called from a dispatched workflow on main and from the push of a tag expanded into the three image jobs and a skipped edge. The image was built locally from a context made the way the job makes it, around the published seed of 3b6b8355 compiled on Linux: 141 seconds with the playground compiled and 39 with it taken from playground-compiled/, the target playground gave torb.js and torb.wasm in three seconds from the builder's cache, both images held the same 894 files, and the image served /, /play, /docs/latest/ (linked to /docs/main/), the reference and torb.wasm. Only the forge shows the rest: the cache entries that ci.yml and this job share, the token for a push, the builder on the runner, and the minutes above.

7.12 Registries compared#

What is taken: JSR's mandatory scopes and its similar-name rule; Hex's signed registry, which makes mirrors cheap; crates.io's sparse index and its lesson that an index must not be a clone; Go's directory hash and its "a version lasts forever"; pub.dev's verified domains, without a dependency on one company's console; everybody's trusted publishing. What is left: install scripts (npm), built artifacts in a source registry (npm, PyPI), a single identity provider (crates.io, JSR), revert windows (Hex, npm), and a registry that is the version control host (Go).

7.13 The client, as built (2026-09-26)#

Slice 11 without its signatures, and slices 4 to 6 as far as the client needs them. The commands are torb add, remove, update, install and publish (docs/tooling/torb-add.md and the pages beside it); the resolver is PROJECT.md section 6a's PubGrub; everything is TorbScript, with no new native. What was open above is decided here:

torb publish against 7.2's steps. Step 1 is built (every refusal at once). Step 2 evaluates project.trb in the sandbox and writes the settings block into the workspace's lock; the archive's own lock holds that block and the workspace's graph as information. Step 3 is not: the sandbox does not record which variables and files an evaluation read, so there is nothing to print. Step 4 is torb check of the package against its locked graph, not --every-target. Step 5 is built, with the summary above. Step 6 writes a file: registry, and since 2026-09-27 uploads to a registry on the network with a token or through trusted publishing (7.11, "The root server and the write service, as built").

Not built in this round, and why: the write service, accounts, tokens, trusted publishing and the compose deployment (7.11, the next round - built 2026-09-27); signature checks and key rotation (no Ed25519 - built 2026-09-27, section 7.14); yank, owner, login (built 2026-10-09, in the table above), audit (built 2026-10-12: the lock against the yanks and deprecations of the indexes), vendor and deprecate; mirrors in ~/.torb/config.trb (built 2026-10-09, section 7.5); git: and archive: sources (both built 2026-10-12, PROJECT.md section 7 "As built"); two majors of one package in one graph (built 2026-10-14, PROJECT.md section 6a: resolved and locked 2026-10-12, checked 2026-10-13, lowered and built under name@major identities); HTTP range requests for an index that grew.

7.14 The signed index, as built (2026-09-27)#

Every record of an index file is signed with the registry's Ed25519 key, and torb checks every record it reads before resolution sees it. std/signature - Ed25519 of RFC 8032 in TorbScript, over the Sha512 std/digest gained for it - made it possible without a native. compiler/src/package/signing.trb is shared by the write service and the client, so what is signed and what is checked is one function. What 7.4 left open is decided here:

Speed: a native binary verifies about 1 000 records a second (docs/standard-library/signature.md), so a resolution that reads a hundred index files of ten records each spends about a second on them; torb is native. The VM verifies about 20 a second.

Tested: compiler/tests/packages.test.trb - the text of a record, a signed index that verifies, a changed, moved, appended-again or unsigned record and another key that do not, trust along endorsements, and the shipped key of packages.torb.dev trusted offline without ever being pinned; tools/registry/tests/server.test.trb - index/config.trb at the start, every record the registry wrote verifying, a successor announced once; tools/registry/tests/client.test.trb - torb add from the registry's files over HTTP pins the keys, and a changed record and a replaced list of keys are refused.

Built (2026-09-28): packages.torb.dev opened with its production key, ed25519:d0f14d661e7db9d83c2807b8fa2c27b034dc724f8f66ec3ad43fd5ae6d04d7c4, listed in shippedKeys of compiler/src/package/registry.trb (docs/contributing/releasing.md, "The root server").

Not built: naming a registry's key in project.trb or ~/.torb/config.trb instead of trusting it on first use; a command that forgets pinned keys (deleting the file under <cache>/keys/ is the way); the tombstones of 7.3.

8. Terminology#

Recommendation: keep "package". It is the word the repository already uses consistently for the unit a registry holds, and the question the owner asked — is it the right word — has a clear answer once the five neighbouring words are put side by side.

How the repository uses them today (counted as whole words in docs/, CONCEPT.md, compiler/src and std/):

No other word for the unit was ever proposed: neither the documents, CONCEPT's decision log nor the commit messages discuss one. The one wobble is the glossary's "Workspace": "naming several member projects", where PROJECT.md says a member is a package. The fix is one sentence in the glossary, and it is a slice: every package is a project; a project is a package when it has a name and something to produce; a workspace root that only lists members is a project and not a package. "Project" is the working directory and its file, "package" is the thing with a name that others depend on.

What other ecosystems call the unit:

Why "package":

1. It means exactly one thing here, and a full word that needs no gloss is the repository's naming rule. A themed word — crate, gem, pod — has to be learned and then explained next to the word it replaces in every error message, every page and every conversation with somebody arriving from another language.
2. "Module" is taken, for a file. Go's use (module = the versioned unit) is the one alternative with a technical argument, and it would collide with 1 909 existing uses meaning something smaller.
3. The owner already chose it for the host name: packages.torb.dev.
4. The themed words that fit "Torb" collide. Rune (Norse, like the name) is a Unicode code point in Go and in text handling generally, which is std/text's territory; forge is a code-hosting word; crate and cargo are Rust's.

Themed alternatives, only as options for the owner's taste (none recommended): rune (Norse; collides as above), saga (Norse; long-running process in other vocabularies), cub (from "björn", bear; playful), kit (short, neutral, but a kit is usually a toolkit), parcel (a JavaScript bundler's name). A themed name for the registry alone — den, hoard — would leave "package" as the unit and only brand the site; that costs little, and it is a taste question.

9. Governance and legal#

• License — recommended: Apache-2.0 WITH LLVM-exception for the toolchain, std and runtime/. The runtime and the parts of std a program uses are compiled into every user's binary; under plain MIT or Apache-2.0 that binary would technically have to carry the notice. The LLVM exception (used by LLVM and Swift) removes exactly that obligation for code embedded by compilation, and Apache-2.0 carries an explicit patent grant. Dual MIT OR Apache-2.0 (Rust's choice) is the alternative, and settles the embedding question by convention rather than by text. This is the owner's decision (question 5); before it, nothing may be published.
• Contributions: the Developer Certificate of Origin (Signed-off-by), no contributor license agreement — unless the owner wants to be able to relicense later, which is the one thing a CLA buys (question 6).
• Name and trademark: a short policy on torb.dev, modelled on the Rust and Python ones: the name and the logo may be used to refer to the language and in community projects; not for a fork that presents itself as TorbScript, and not in a product name that suggests endorsement. Before registering anything, a search of the name in the EU and US trademark registers and of torb/.trb as existing product names and file extensions.
• Security policy: torb.dev/security and /.well-known/security.txt (RFC 9116) with security@torb.dev, an acknowledgement within a stated number of days, coordinated disclosure, advisories in the database of 7.6. The registry's own incidents are reported on the same page.
• Code of conduct: the Contributor Covenant, current version, with the enforcement contact on torb.dev.
• Contribution flow once public: issues and pull requests on github.com/TorbScript/language; CI runs tier A on every pull request and tier B where the change touches the IR, a back end or runtime/ (compiler/CONTRIBUTING.md); the two-commit rule of RUST-EXIT section 4.2 and docs/design/ records stay how a larger change is proposed — a design record is the RFC process, and it already works. Planning happens in the open, in the issues and milestones of git.torb.dev, docs/ROADMAP.md and the design records; there is no private channel in the repository (question 8).

10. Slices#

Each slice lands with the gates green, like every other slice in docs/design/. Slices 1 to 7 can be done now, beside the work on milestones 7 and 8, without touching a file that work touches.

11. What this is not#

• Not a date for 1.0. The launches are gated by lists, and the lists are the repository's own milestones. The releases themselves follow the calendar since 2026-09-29 (section 3): the milestones decide what a minor carries, the first Tuesday when it comes.
• Not a registration. Nothing here was registered, published, announced or configured: not a DNS record, not an account, not a package name on another registry.
• Not a new build system. The registry stores source and runs nothing; torb publish checks, it does not build.
• Not a second manifest format. The index, the owner files and the user's config.trb are receiver scripts in the vocabulary the lock already uses; the only JSON is what a browser reads (the search index) and what another ecosystem's scanner reads (the OSV export).
• Not a decision about foreign functions. Section 2 names the question the registry needs answered; the answer belongs to the design of foreign: open, owner decision (#84), see FOREIGN.md section 5.3.

12. Open#

Everything technical above is decided. These are the owner's: questions of direction, taste or money.

1. The word for the unit. Section 8 recommends staying with "package" and lists themed options only for completeness. A themed name for the registry alone (den, hoard) is possible without changing the unit.
2. The registry's server language. Decided: TorbScript, which waits for the HTTP server of milestone 10. The alternative is a small server in another language (Go, Rust) to open the registry right after milestone 8, rewritten in TorbScript later; the protocol of 7.4 is the same either way.
3. Which std packages 1.0 promises. The recommendation: only what is finished and used — the prelude's packages, fs, io, process, environment, time, json, test, project, sandbox, os, http once it runs. The domain packages (linear, geometry, the planned ecs and machine learning packages of milestone 10) either wait for a later minor or live under a separate owner on the registry (torbscript/..., as Go keeps golang.org/x) until they are ready. "The standard library is part of the language" (PROJECT.md section 10) makes this a question about what the language is.
4. The stability promise and the cadence. Section 3 proposes Go-style strict compatibility within 1.x, no editions, and a minor release every six weeks. Confirm, or say which surface should promise less. Decided by the owner: Go-style stability without editions, and a release every six weeks. Changed by the owner's delegation (2026-09-29): a minor on the first Tuesday of every month, its release candidate a week before on the preview channel, patches whenever a fix is ready, alpha and beta only before a major, no long-term support (section 3).
5. The license. Apache-2.0 WITH LLVM-exception (recommended) or MIT OR Apache-2.0. Without an answer nothing may be published. Decided by the owner: MIT, and MIT-0 for runtime/ and std/, whose code ends up in every program; every release archive carries the three LICENSE files.
6. DCO or CLA. DCO is recommended; a CLA only if relicensing later should stay possible. Decided by the owner: DCO.
7. Money. Apple's developer membership for notarization, a Windows code signing certificate or service, the object storage and CDN of the registry, and mail for torb.dev. Every one of them can wait for the preview except mail, which security@torb.dev needs.
8. What becomes public. The repository including docs/design/, docs/internals/ and the history is recommended. Decided: the private planning file left the repository, and what in it was still to be done moved to docs/ROADMAP.md, the design records and CONCEPT's "Open Questions".
9. Domain-verified owners with a dotted name. PROJECT.md reserved acme.com/x as a name form. The registry could use it for owners that proved the domain (7.1). Recommended: not at launch; a verified domain is a badge on a plain owner, and the dotted form stays reserved.

13. The release pipeline, as built#

Status: written, not yet run. The workflows, the composite actions and the scripts below exist in the repository; no workflow has run on GitHub yet, no seed and no release has been published, and the Linux and macOS halves of the runtime have still never been compiled (fact 4) - among them the whole POSIX side of the network (runtime/os/posix_io.c, the pollers epoll.c and kqueue.c, runtime/tests/io_test.c) and of std/os (posix.c, linux.c, bsd.c, macos.c). The first CI run is the first compile of all of it, and every job that can reach them runs the runtime's tests and the conformance suite. The Windows half of every script was run on the maintainer's machine; what the first run on the other targets is expected to report is listed at the end of this section. How the owner cuts a release is docs/contributing/releasing.md.

Since 2026-09-27 the pipeline runs on the forge (section 14): the workflows moved from .github/ to .forgejo/, the seeds and the releases to git.torb.dev, the images to cr.torb.dev, and the signature from keyless Sigstore to the project's key. The jobs and their reasons below are the same; where the forge changed one, this section says so, and the first runs it reports were GitHub's.

The files#

The seed, published#

Decision: a seed is published as torb-seed-<commit>.tar.gz on one release tagged seeds - of GitHub when this was built, of the forge at git.torb.dev since 2026-09-27 - listed in seeds.txt beside it, and fetched over plain HTTPS without gh.

torb-seed-1ae963fa1234/
├ program.c      the compiler's C, emitted by the compiler of that commit from its own sources
├ program.hash   what `torb run` keys its cache on
├ commit         twelve hexadecimal digits
├ runtime/       the runtime of the same commit: include/, *.c, os/*.c - not its tests
├ build.sh       tools/build-seed.sh: `sh build.sh` writes ./torb with the machine's C compiler
└ README.md

• The runtime travels with the C. program.c calls the runtime of the commit it was emitted at; the runtime of a later commit may have renamed a native that C still calls. tools/pack-seed.sh therefore takes runtime/ from git at the seed's commit, never from the working tree - which is also why seed/program.c in the main checkout only works with a runtime that has not moved on.
• seeds.txt is one line per seed, newest first: <commit> <sha256> <archive>. An archive is found in the directory of the index, so a mirror, a fork or a local directory is one variable away (TORB_SEED_INDEX); the tests of tools/fetch-seed.sh use a file:// index.
• One release for every seed, rather than a tag per seed: no tag noise, one URL scheme, and a prerelease is never the repository's "latest". The seeds tag points at whatever commit it was created on, which means nothing. Every seed is kept; at about 6 MB each (5.9 MB for the 106 MB program.c of 653af8bb, gzip -9) pruning can wait.
• .tar.gz, not .tar.xz (4.1 MB): every machine that has tar has gzip, and the archive is not downloaded often enough for the difference to matter.
• Reproducible: entries sorted, owner 0, modes fixed, every timestamp the commit's, gzip -n. Packing the seed of 653af8bb twice gave the same SHA-256.
• Verification is the SHA-256 of the index, over HTTPS. The signature of a release (below) covers the seed as one of its assets; a seed published by the nightly or the seed workflow carries none, because it is no release.
• Two indexes. tools/fetch-seed.sh reads the forge's (public, no token), and GitHub's only when the forge's cannot be read or does not list the seed asked for - the seeds published before the move, until tools/migrate-seeds.sh has copied them. GitHub's repository is private and answers the plain download URL with a login page; with GH_TOKEN or GITHUB_TOKEN set, tools/fetch-seed.sh goes through its REST API instead (the release of the tag, the asset's id, the asset with Accept: application/octet-stream) - still curl or wget and no gh. A private forge would take TORB_FORGE_TOKEN.

Where tools/bootstrap.sh takes its seed from, in this order: $TORB_SEED (never falls back), seed/torb or seed/program.c, the newest archive in ../torbscript-seeds/, build/seed/torb - and when there is none, tools/fetch-seed.sh is run for the newest seed (TORB_SEED_FETCH=0 forbids it). When step 1 fails with a seed that was fetched earlier, the newest is fetched once more and tried before the archives, because the fetched one may predate the first commit of a breaking change.

When a seed is published: by the nightly and by every release, once linux-x64 has bootstrapped and passed tier A and tier B - the other targets are not waited for, since the seed is C and the agree job shows the C is the same on every target - and at once by the seed workflow. That workflow is the CI half of the two-commit rule (compiler/CONTRIBUTING.md): the first commit teaches both forms, seed publishes its seed, and only then can the second commit bootstrap in CI and in a fresh clone.

The first seed cannot come from CI, which needs a seed to build anything. On the forge it comes from GitHub (tools/migrate-seeds.sh, which copies every seed GitHub's index lists) or from the main checkout: sh tools/pack-seed.sh seed and TORB_FORGE_TOKEN=<token> sh tools/publish-seed.sh build/seed-archive/torb-seed-<commit>.tar.gz. Both publish through tools/forge.sh - curl and the forge's REST API, no gh; the release is created as a prerelease on first use, and seeds.txt is replaced by deleting the asset and uploading the new one.

CI: the jobs and why#

Why tier A and tier B run on one target only. Nearly every gate tests the compiler, and the compiler is the same C on every machine - which the agree job proves on every run, and which is the strongest cross-platform statement the repository can make cheaply. On the forge's one runner it is proven differently than on GitHub's four: the C a host emits for a target is a function of the target, so the check compares what several hosts emit for every one of the nine targets (the eight machines and browser-wasm64, the playground's), and with a single host it shows that every target lowers and that --target of the host itself reproduces the bootstrap's C. The lists of the other runners, of the GitHub mirror's machines and of the maintainer's own (sh tools/agree.sh emit build/release/torb build/hosts/mine.txt) are compared the same way; measured on 2026-09-27, the eight emissions take four to five minutes each on the maintainer's machine, and the C differs only between groups of targets (windows; linux and macos-x64; macos-arm64 and the BSDs). What differs per machine is the C compiler, the C library and the runtime's platform layer, and exactly those are exercised by the bootstrap (the compiler builds itself natively, twice or three times), the conformance suite (every behaviour, built and run natively, byte for byte against its expectation) and the runtime's own tests. Tier A on macOS would cost a macOS hour per push for torb test compiler/tests, which checks what the agree job already shows is identical. linux-x64 carries both tiers because it is the cheapest runner and the most common machine of the people who will send pull requests. Tier A and tier B run as two jobs after one bootstrap, so the wall time is the longer of the two and not their sum.

Why the release scheme still meets section 5's "tier A and tier B on every tier 1 target" in substance: the gates that can differ between machines run on every one; the ones that cannot run once. When a difference turns up that only a full tier catches, the fix is to move that gate into the portable job, not to run everything everywhere.

Why the compilers are these. gcc on Linux is the compiler the maintainer's gcc 13 is closest to, so the first Linux run tests the POSIX runtime and not a change of compiler; clang meets the runtime once more on Linux (tier B's last step) and the generated C on macOS, where it is the only one. On Windows clang targets MSVC and torb build passes -lm, which MSVC does not have, so the Windows job installs gcc from the MSYS2 that every Windows image has.

Memory and time. TORB_BUILD_SLOTS=1 in every job: one cc1 over the compiler's C takes 1.5 to 2 GB, a test suite's C is larger, and the forge's runner runs two jobs at once beside the forge itself - its machine wants 8 GB for them. Timeouts: 90 minutes for the Linux bootstrap, 120 for each tier, 60 for the agreement of the C, 150 for a portable target (a first seed compile, the whole conformance suite), 60 for a cross-compiled one (about ten minutes, most of them the emission and the compile of the C).

Caches (the runner's own cache server; a runner without one only loses the time), written only by a push to main so a pull request reads them and never fills the cache: build/release keyed by the target and the hash of everything torb is built from (compiler/src, the manifests, std/, runtime/, tools/bootstrap.sh) - a hit skips the bootstrap, because those sources were bootstrapped on that target before - and build/seed keyed by the target and the seed's commit, so an unchanged seed is compiled once. The one exception is the archive of the pinned Zig, keyed by tools/fetch-zig.sh and written by any run that missed it: only a nightly or a release reaches it, and it is checked against the pinned SHA-256 each time it is used, so an entry can save a download and never slip in another file.

Concurrency and permissions. ci cancels the run a newer push to the same branch or pull request supersedes; nightly, release and seed never cancel. On the forge no workflow has a permissions: key - Forgejo ignores a job that has one - and nothing writes with the job's automatic token: the jobs that publish set enable-openid-connect: true and write with the token of an Authorized Integration, whose rules admit only the named workflow files, refs and events of this repository (section 14). The signing key is a secret only publish of release and nightly and the image jobs read. Every checkout has persist-credentials: false, every action is pinned by commit, a pull request from a fork runs nothing, and no workflow uses pull_request_target.

Versions, tags and channels#

• A release is a pushed tag and nothing else: v0.MINOR.PATCH for a stable release, and since 2026-09-29 a pre-release v0.MINOR.0-rc.N - before a major vMAJOR.0.0-alpha.N, -beta.N and -rc.N (section 3). release.yml refuses a tag of another shape or with a leading zero, a stable release that is not 0.MINOR.PATCH - 1.0 is released by changing that check - a tag whose number without its suffix differs from version in project.trb, compiler/project.trb or editors/vscode/package.json, or from languageVersion in compiler/src/package/version.trb (section 3: one number, the editor extension's and torb --version's included), a commit that is neither on main nor on release/MAJOR.MINOR of its number, and a repository without a LICENSE (section 9; the owner chose MIT, question 5) - the forge's repository is public.
• A pre-release is a prerelease of the forge: never its latest release, listed by release-sync on the preview channel, its images tagged <version> and preview instead of latest, and neither publish-packages nor the stores run for it - publish-extension says so in a notice. Its assets are named after the whole version, torb-0.2.0-rc.1-linux-x64.tar.gz and torbscript-0.2.0-rc.1.vsix, whose manifest says 0.2.0 and marks it as a pre-release. Its notes are docs/releases/<version>.md, or else those of its number, docs/releases/0.2.0.md, with a paragraph that names the channel.
• A release of release/MAJOR.MINOR - a later candidate or a patch, whose commit main does not have - keeps its seed out of seeds.txt: every clone of main bootstraps from the newest seed there, and the release branch's compiler may not read what main has taught since. The seed stays an asset of the release. ci runs on every push to release/* as on main, and bootstraps from main's newest seed, so main keeps reading every form the maintained release branch uses until the next minor is out.
• The VS Code extension follows the release, and the nightly follows itself. A release publishes torbscript-<version>.vsix, the file among its assets, to the Visual Studio Marketplace (vsce publish, the secret VSCE_PAT) and to Open VSX (ovsx publish, the secret OVSX_PAT), each only where its secret exists, after the release is on the forge. A nightly carries torbscript-nightly-YYYYMMDD.vsix to both stores the same way, marked as a pre-release, as VS Code's "Switch to Pre-Release Version" - vsce verify-pat and ovsx verify-pat run first, so a wrong publisher or namespace fails clearly. Its manifest is stamped with a store version of its own, MAJOR.(MINOR+1).YYYYMMDD of package.json's version and the nightly's date (tools/package-extension.sh, 0.1.0 becomes 0.2.20260929) - not the toolchain's number, which belongs to releases: a later stable 0.2.0 is then lower than the nightlies of its cycle, so pre-release users stay ahead of release users and a release never collides with a nightly's number. A second nightly of the same day has the same store version and is skipped (--skip-duplicate). A release candidate's torbscript-0.2.0-rc.1.vsix is marked as a pre-release too, but reaches neither store: its version, 0.2.0, would collide with the stable release that follows it.
• stable: the release, marked latest, kept forever. preview: a pre-release, kept like a release. nightly: a prerelease nightly-YYYYMMDD of main, made only when main changed since the last one and every target is green, deleted with its tag after 30 days. A second run on one day replaces that day's nightly.
• The release notes are docs/releases/<version>.md when it exists (section 6 plans that folder), plus the commands that verify a download.

What a release contains#

• The seed is beside the archives, not inside each: it is the same file for every target and 6 MB.
• Every tier 1 target (since 2026-09-29): linux-x64 from its bootstrap; windows-x64, linux-arm64 and macos-arm64 from their own runner where the forge has one of that label (section 14), and cross-compiled on linux-x64 where not ("Cross-compiled archives", below). The release notes list the targets and say which were cross-compiled, and a package manager channel whose archives are missing renders nothing.
• The binaries: linux-x64 and linux-arm64 compile the fixpoint's program.c with musl-gcc -static (section 5 asks it for linux-x64; linux-arm64 gets the same so that one Linux binary runs on every distribution of either architecture), and the job fails if ldd finds it dynamic. windows-x64 and macos-arm64 ship the bootstrapped binary itself; the Windows job fails if torb.exe imports a DLL a Windows machine does not have, the macOS job runs codesign --verify (the linker's ad hoc signature, section 5). A cross-compiled binary is the same C of the same commit, compiled by the pinned zig cc for the same C library - static musl, MinGW-w64 on the UCRT - and put through the same checks by other means (below).
• Every release binary is smoke-tested as a download: laid out by tools/package.sh layout, started from a directory outside any checkout with no TORB_STD or TORB_RUNTIME, it checks, builds and runs a program. A cross-compiled one is started under wine or qemu-user, and macos-arm64's not at all (below).
• The archives are packed on Linux, one job for all targets, with GNU tar and zip: sorted entries, owner 0, fixed modes, the commit's time. The binaries inside are not yet reproducible across runner images (below).

Cross-compiled archives (2026-09-29)#

Until this, the nightlies on git.torb.dev carried torb-<version>-linux-x64.tar.gz and nothing else a machine could run: the forge has one runner, linux-x64, and an archive was built only on a runner of its target, so nobody on Windows, macOS or an arm64 Linux could install TorbScript - install.ps1 found no .zip, install.sh no archive of its machine, and the Scoop, Homebrew and winget steps of a release skipped themselves.

Decision: when a nightly or a release packages, the forge's linux-x64 runner cross-compiles the release binary of every tier 1 target that has no runner of its own - windows-x64, linux-arm64, macos-arm64 - with one pinned, hash-verified zig cc, section 4's managed compiler; each binary is checked, started under an emulator where one exists, and packed by tools/package.sh exactly like a native one. A target's own runner, once TORB_RUNNERS names it, replaces its cross job, and its binary is the one released.

• The C is the target's own. The job runs torb build ./compiler --emit-c --target <target> with the linux-x64 compiler of the run (tools/cross.sh) - the path the playground takes to browser-wasm64 with emscripten. The C a host emits for a target is the C that target's bootstrap emits, which the agree job checks on every run, so the binary is the compiler a native bootstrap of the commit builds, compiled by another C compiler. The runtime is compiled for the target in the same command (tools/build-seed.sh, with $TORB_CC a wrapper of zig cc -target <triple> and the TLS of vendor/ as always), and the archive gets the std/ and runtime/ of the commit beside it.
• The C libraries are the native builds': x86_64-windows-gnu is MinGW-w64 on the UCRT, as MSYS2's UCRT64 gcc builds windows-x64 on its runner (the binary imports api-ms-win-crt-*, kernel32, advapi32 and shell32); aarch64-linux-musl is static musl, as musl-gcc -static builds linux-arm64; aarch64-macos.13.0 links libSystem and nothing else and runs on macOS 13 and newer, Zig's default, named so a new Zig cannot move it. tools/build-seed.sh asks the compiler for the machine it builds for (-dumpmachine) before it adds -pthread, which a Windows target must not get from a Linux host.
• windows-x64 keeps its icon and version: zig rc compiles tools/windows/torb.rc into a .res that zig cc links (tools/windows/resource.sh with an output ending in .res), with Zig's own preprocessor and <winver.h> - no MinGW on the runner at all.
• Zig is pinned by version and by the SHA-256 of each host's archive in tools/fetch-zig.sh (0.16.0; the x86_64-linux archive for the runner, x86_64-windows, aarch64-linux and aarch64-macos for people), each archive's minisign signature checked against the Zig Software Foundation's key when it was pinned. It downloads from Zig's community mirrors in a random order and from ziglang.org last, as ziglang.org asks of automated downloads, and keeps nothing whose hash is not the pinned one. The job caches the archive.

What is tested before anything is published (.forgejo/actions/cross, a job per target, and tools/cross.sh):

What is not tested before publishing, on any of the three: the conformance suite, the runtime's tests, a native torb build with the machine's C compiler and the archive's runtime/, and anything wine or QEMU emulates rather than Windows or Linux itself - and for macos-arm64 whether the binary starts at all. A cross-compiled binary is smoke-tested, never gated. Two things cover it afterwards: the GitHub mirror runs bootstrap, the conformance suite and the runtime's tests of each target's own native build after every push (portable.yml), and every morning its job download installs the published nightly from torb.dev on real windows-x64, linux-arm64 and macos-arm64 machines (and linux-x64) with tools/install.sh and tools/install.ps1, and checks, runs and natively builds a program with it - the first time a cross-compiled binary meets its machine, and a report, not a gate. The release notes of a nightly and a release name the targets that were cross-compiled. A red cross job stops the nightly or the release like any other red gate.

The nightly's images stay linux/amd64: images.yml builds linux/arm64 images when a release has a linux-arm64 toolchain, every nightly has one now, and its three arm64 build stages under QEMU would take hours of the one runner every night, for images the root server (x64) never pulls. A stable release still gets both.

Verified when this was built, 2026-09-29: on the maintainer's Windows machine, tools/cross.sh with the Windows build of the same Zig built windows-x64's torb.exe from the C of the commit in five and a half minutes; that binary passed tools/smoke-test.sh natively and the conformance suite natively (256 of 256 programs) and in the VM (259 of 259) - on its own machine, which the forge's runner cannot do. The same C compiled by the machine's MinGW gcc 13 (x86_64-ucrt-posix-seh) through tools/build-seed.sh passed the smoke test too, but that torb.exe - like every bootstrapped one on that machine - imports libwinpthread-1.dll, which a gcc of the posix thread model links in although the runtime uses no pthreads on Windows, and which the check of .forgejo/actions/portable refuses: MSYS2's UCRT64 gcc has the same thread model, so a native windows-x64 runner is expected to meet that check red until the release step links winpthreads statically. The Zig build imports no such DLL. In the forge runner's image (catthehacker/ubuntu:act-24.04, under Docker, as root), with the linux-x64 compiler compiled from the same commit's C: tools/fetch-zig.sh fetched from a different mirror on each of two runs, tools/cross.sh built each of the three in five to seven minutes - emission included, and every program.hash the same as the bootstrap's - windows-x64 passed the smoke test under wine in 30 seconds, linux-arm64 under qemu-aarch64 in two and a half minutes, macos-arm64 passed its checks, and tools/package.sh packed archives of 6.7 to 7.5 MB, as large as linux-x64's native one. Installing wine and qemu-user took 40 seconds. tools/install.sh installed the linux-arm64 archive from a file:// channel of those archives and the installed torb checked and ran a program under qemu, and torb.exe of the unpacked .zip did the same under wine. The workflows pass forgejo-runner validate of runner 12.13.2 (the one Forgejo 16.0.5 builds in) and 13.2.0, and portable.yml passes actionlint. The first nightly on the forge is the first run of the jobs themselves.

Signing#

Decision (2026-09-27, the forge): cosign sign-blob over SHA256SUMS with the project's own key, in the publishing job; the signature SHA256SUMS.sig is a release asset, the public half of the key is tools/deploy/cosign.pub in the repository and https://torb.dev/cosign.pub, and the same key signs the container images. The private half is the secret COSIGN_PRIVATE_KEY of the repository, with its password COSIGN_PASSWORD. Signing stays on the pinned cosign 2.4.1 (.forgejo/actions/cosign): 3.x refuses sign-blob --output-signature without --bundle, and only --new-bundle-format=false --use-signing-config=false keeps the legacy .sig. Verifying in release-sync is cosign 3.1.4 (tools/deploy/Dockerfile.release-sync), because the Go modules of 2.4.1 and 2.6.5 carry fixable HIGH and CRITICAL findings that 3.1.4 does not; it verifies the .sig of 2.4.1 (measured). Neither writes to nor reads from Sigstore's transparency log.

cosign verify-blob --key https://git.torb.dev/torbscript/language/raw/branch/main/tools/deploy/cosign.pub \
  --signature SHA256SUMS.sig --insecure-ignore-tlog=true SHA256SUMS
sha256sum --check --ignore-missing SHA256SUMS

Why the keyless signature of the first decision (below) could not move with the rest. Keyless signing needs a certificate from Sigstore's Fulcio, which issues one only for the OIDC identity of an issuer it trusts - GitHub's, among a handful - and git.torb.dev's Actions issuer is not one of them (an issue asks Sigstore to trust Codeberg's; a private instance never will be). The choices were a key of the project, a Sigstore of the project's own (Fulcio, Rekor and a trust root to run and back up), or signing on the GitHub mirror, which would make the mirror the signer of what the forge publishes. A key it is:

The first decision, while releases were made on GitHub (kept for the releases made there, and for release-sync with RELEASE_SYNC_FORGE=github): keyless Sigstore with cosign sign-blob over SHA256SUMS, in the publishing job, with that job's OIDC identity; the bundle SHA256SUMS.sigstore.json was a release asset.

Attestations were to be added beside the signature once the repository was public; on the forge there are none to add.

Where this departs from sections 4 and 5, and why#

• Native runners, and one pinned zig cc only where there is none. Section 4 builds every target with a managed zig cc so binaries are reproducible; that toolchain (torb toolchain add c, slice 9) does not exist yet. linux-x64 and every target with a runner are built by the runner image's compiler, so their binaries are reproducible for one image and not across images. Since 2026-09-29 the targets without a runner are built by a pinned Zig that tools/fetch-zig.sh fetches ("Cross-compiled archives"): the pipeline's half of section 4, whose binaries depend on the pinned archive and not on the runner's image - but section 5's "built twice on two runners and compared" is still not done for any of them. The C (program.c) is reproducible already, and the agree job checks it across four machines on every run.
• linux-arm64 is static musl too, above.
• FreeBSD (tier 2) is not in the pipeline; it needs a virtual machine on a Linux runner.

What the first run is expected to report#

None of this has been compiled on Linux or macOS; the pipeline is built to say where it breaks, one job per target with fail-fast: false, so one target's failure never hides another's.

1. Every job, until the first seed is published: tools/fetch-seed.sh finds no seeds.txt (see "The first seed").
2. macOS, the feature macros: platform.c, os/posix.c, os/posix_io.c and tests/console_test.c define _POSIX_C_SOURCE 200809L, which on macOS alone hides every Darwin extension - pthread_cond_timedwait_relative_np (the macOS branch of torb_condition_wait), _SC_NPROCESSORS_ONLN (the processor count of the worker pool) and SO_NOSIGPIPE (without which a write to a closed socket kills the process with SIGPIPE, since macOS has no MSG_NOSIGNAL either). The four files now define _DARWIN_C_SOURCE beside it on Apple, which shows the extensions again; that is the documented switch, but it has not met a macOS compiler yet, so this item stays until the first run confirms it.
3. macOS, finding the toolchain: Process.executablePath() answers None (fact 5), so the smoke test of a release fails - correctly, a downloaded torb cannot find its std/ today. The gates are unaffected: they run in the checkout, where std/ is found above the working directory.
4. The generated C under clang: torb build compiles with -Wall -Wextra -Werror, and the C has only ever met gcc 13. Any warning clang adds stops every macOS build.
5. linux-arm64: char is unsigned there. A comparison of a char with a negative number becomes a -Wtype-limits warning (part of -Wextra), and with it an error; the same code is silent on x64.
6. Windows on CI: MSYS2's gcc is newer than the maintainer's 13; a warning a newer gcc adds to -Wall -Wextra (gcc 15 added -Wunterminated-string-initialization there) fails the generated C under -Werror.
7. The conformance suite on POSIX: Process.run goes through /bin/sh there (runtime/README.md), so a program that cannot be started is the shell's exit code 127 and not a failure; a program whose expectation was recorded on Windows and depends on that differs.
8. The static musl binary calls popen and fork like the glibc build, but it has never run; the smoke test is the first thing that exercises it. Name resolution (getaddrinfo) in a static binary is musl's own resolver, which reads /etc/resolv.conf and /etc/hosts and nothing of NSS.
9. The network on POSIX: io_test.c and the network programs of the conformance suite open sockets on the loopback; a hosted runner allows that, but the epoll and kqueue pollers, the non-blocking connect and the resolver thread have only been reasoned about, never run.

What the first runs reported#

The first runs on the four targets (September 2026) failed on three of the items above and on three things nobody had expected; all of them are fixed:

• Item 7: files and process-run-input printed true on Linux and macOS where Windows prints false. The POSIX half of Process.run is fork plus execvp now, with no shell, so a program that is nowhere is a failure on every target.
• Item 3: Process.executablePath() answers on macOS, through _NSGetExecutablePath and realpath (runtime/os/macos.c); FreeBSD still answers None.
• Item 6: MSYS2's gcc 16 refused the generated C with -Warray-bounds ("array subscript 'torb_text[0]' is partly outside array bounds of '_Bool[1]'"). It is a false positive about gcc's own speculation: -fspeculatively-call-stored-functions, new in gcc 16, guesses one function for every call through a torb_closure, and the guessed branch, which is never taken, reads a bool result as the call's own type. torb.h turns the warning off for gcc 16 and later.
• Not expected: tier B's torb test --vm of the std packages ran out of the VM's 64 slots for counted element types once the text formats had joined. A descriptor the VM makes is told which one it is now (torb_contextual_element, runtime/element.c), so the VM makes as many as a program needs.
• Not expected: the tests of the worker pool (runtime/tests/pool_test.c) failed now and then on Linux (6 of 40 runs with clang 19), which the Windows machine had never shown: three races of runtime/task.c let a task run on two workers at once or be freed while its start still queued it. After the fix, 0 of 100 runs with clang 19 and gcc 16.
• Not expected: the Windows runner's Git checks files out with CRLF (core.autocrlf), which put \r into every multi-line string literal: interpolation printed it, and the compiler's own C differed from the other targets' in the agree job. .gitattributes turns the conversion off (* -text).

Items 2, 4, 5 and 9 did not come up: macOS builds with the feature macros as they are, clang and the unsigned char of arm64 add no warning to the generated C, and the network programs pass on every target.

What the owner set up on GitHub#

While GitHub carried the pipeline, this was the owner's list; section 14 and docs/contributing/releasing.md have the forge's, which replaces it.

• The first seed, once, as above.
• Actions minutes: on a private repository hosted runners are billed, macOS at ten times and Windows at twice the Linux rate, and ubuntu-24.04-arm is a free standard runner only for a public repository (for a private one it needs the plan's arm64 runners). ci.yml already keeps macOS and linux-arm64 to the changes that can affect them while the repository is private; making the repository public (question 8) makes every standard runner free and turns them on for every change.
• Workflow permissions: Settings -> Actions -> General: "Read repository contents" as the default token permission (every workflow asks for more where it needs it), and allow GitHub Actions to create releases.
• The release environment: created by the first release run; add required reviewers to it to hold every release for one click after the gates.
• Tag protection: a ruleset on v*, nightly-* and seeds so that only maintainers (and the Actions bot for nightly-*) can create them.
• Branch protection on main: require the checks gates / tier A (linux-x64), gates / bootstrap (linux-x64), gates / bootstrap and conformance (windows-x64) and gates / every target emits the same C before a merge.
• The package manager channels (publish-packages of release.yml, section 5): create TorbScript/homebrew-tap and TorbScript/scoop-bucket, each with an empty Formula/ or bucket/ directory; submit the first winget manifest by hand with wingetcreate new (update only ever edits an existing one); add HOMEBREW_TAP_TOKEN, SCOOP_BUCKET_TOKEN and WINGET_TOKEN as repository secrets, each a fine-grained personal access token limited to contents: write of the one repository it pushes to (winget's token needs to open a pull request against microsoft/winget-pkgs, so a classic token with public_repo is what wingetcreate itself documents). None of the three is required: the job skips a channel whose secret is absent (docs/contributing/releasing.md has the full list of one-time setup, including release-sync's).

14. The forge#

Decided by the owner (2026-09-27): the repository, its CI, its seeds and its releases live on the project's own Forgejo; GitHub becomes a mirror and is not deleted. Built on the same day; the server side - the forge, its runner, the compose stack - is the owner's and existed before it.

                git.torb.dev (Forgejo 16.0.5, SSH on port 2223)            cr.torb.dev (the forge's container registry)
  ┌───────────────────────────────────────────────────────────┐        ┌──────────────────────────────────────────┐
  │ torbscript/language   the repository, .forgejo/workflows/ │ ─────> │ torbscript/site, release-sync, registry  │
  │   releases: v*, nightly-*, seeds (seeds.txt + archives)   │ images └──────────────────────────────────────────┘
  │ torbscript/homebrew-tap, torbscript/scoop-bucket          │                    │ pulled by
  │ runner torb-runner-1: ubuntu-latest, ubuntu-24.04 (DinD)  │                    v
  └───────────────────────────────────────────────────────────┘        the root server: torb.dev, packages.torb.dev
        │ push mirror                     │ webhook "published"   ──────────> release-sync -> /srv/torb/download
        v
  github.com/TorbScript/language   .github/workflows/portable.yml: windows-x64, linux-arm64, macos-arm64

What moved, and where it went#

Writing from a workflow: Authorized Integrations#

Forgejo ignores every job whose job or workflow has a permissions: key, and the token it gives a job automatically (forgejo.token) is limited. A workflow of the forge that writes asks for an Authorized Integration's token instead: the job sets enable-openid-connect: true, requests an ID token from $ACTIONS_ID_TOKEN_REQUEST_URL with the integration's audience, and sends it as Authorization: Bearer - or as the password of docker login and of git over HTTPS, which the forge accepts in both places. The forge checks it against the integration's claim rules (the repository by its id, the workflow file, the ref, the event), and the request may do what the integration's permissions allow, as the user who created it. .forgejo/actions/token does the request; the audience is not a secret and lives in a repository variable. Forgejo 16 has no API to create an integration: the owner creates both in the web interface (docs/contributing/releasing.md, "One-time setup"):

• Two integrations, not one: an integration limited to specific repositories may only hold the repository and issue permissions, and pushing an image is a package permission.
• The workflow file of a reusable workflow's job is the calling run's: images.yml runs inside release.yml and nightly.yml, which is why those two are in the image integration's rule, and images.yml itself for a run by hand and for its own push trigger - the site of main (section 7.11), whose token names images.yml, refs/heads/main and the event push, which the rule admits as it stands.
• A reusable workflow says enable-openid-connect: true at its top level, not on its jobs, and the calling job says nothing. A calling job without runs-on is expanded by the forge into the called workflow's jobs, each a job of the calling run; the jobparser (runner 12.13.2, which Forgejo 16.0.5 builds in) re-reads each expanded job from a one-job workflow whose job type has no field for the key, so a job-level enable-openid-connect of the called workflow is dropped, and the calling job's own key is read for the calling job alone, which runs nothing. What survives is the called workflow's top-level key. The first nightly's image jobs failed on exactly this ("this job cannot ask for an ID token") while images.yml run by hand had pushed its images the same day; parsing nightly.yml's call with that jobparser gives the three expanded image jobs false with the key on the job and true with it at the top, and the top-level key serves the run by hand as well. The alternative - runs-on on the calling job, which the forge then leaves unexpanded (expandForJob, the behaviour from before the expansion) and whose runner runs the called workflow inside that one job, under the calling job's key - would put three image builds of up to two hours each into one job of the calling run.
• The patterns are gobwas/glob's, which the forge compiles when the integration is saved; {a,b} is an alternative, * crosses /.
• An hour: a token lives [actions] ID_TOKEN_EXPIRATION_TIME (an hour by default), so every job asks for its token right before the step that needs it, and the image job builds first and pushes from the build cache afterwards.

Runners#

The forge has one runner, torb-runner-1 (labels ubuntu-latest and ubuntu-24.04, the image catthehacker/ubuntu:act-24.04, Docker in Docker, two jobs at a time). Decision: the jobs of the other tier 1 targets are declared in gates.yml and run only for the targets the repository variable TORB_RUNNERS names (windows-x64 linux-arm64 macos-arm64, or any of them), on a runner whose label is the target's name. A job whose label no runner has would wait for ever - "your pipeline will halt", the forge's documentation says - so each such job reads the variable through a first job and has an if: on its output alone, which the forge evaluates itself and skips before any runner is asked. Until those runners exist:

• A release carries their cross-compiled toolchains (section 13, "Cross-compiled archives", since 2026-09-29; until then a release carried the linux-x64 toolchain only): the forge's runner builds them with a pinned zig cc, checks them and starts them under wine and qemu-user, so the Homebrew formula and the Scoop manifest are rendered and winget's update is a command the release job prints. A stable release builds linux/arm64 images from its linux-arm64 toolchain; a nightly builds linux/amd64 ones only (images.yml).
• The GitHub mirror runs the three targets after every push (.github/workflows/portable.yml): bootstrap, check ., the conformance suite, the runtime's tests and the agreement of the C among them - as a report, not a gate, and only while the mirror is public, where GitHub's standard runners cost nothing. Every morning it also installs the newest nightly on the three machines and on linux-x64, with tools/install.sh and tools/install.ps1 from torb.dev, and checks, runs and builds a program with it: the first run of a cross-compiled binary on its own machine.
• Cross-compiling was first considered and left (2026-09-27): windows-x64 with Debian's MinGW-w64 and linux-arm64 with a musl cross compiler would build binaries on the one runner, but nothing could run them there, and a binary no gate has run is not one to release; QEMU would make the compiler's 100 MB of C a matter of hours. What changed the decision two days later is section 13's "Cross-compiled archives": the binary is not bootstrapped under QEMU but cross-compiled, and only started there - wine and qemu-user start it in seconds and minutes - and the mirror runs the published nightly on the real machines.

GitHub as the mirror#

Decision: the forge pushes every change to GitHub through a push mirror, and .github/workflows/ keeps one workflow, portable.yml; the six workflows that built, published and signed on GitHub are deleted, since two pipelines publishing the same release would race. portable.yml reuses .forgejo/actions/portable (a composite action works on both), reads no secret, publishes nothing and fetches the seed from the forge. Recommended over deleting .github/ entirely because it is the only place windows-x64 and macos-arm64 run at all until the forge has runners - and, since the forge cross-compiles their released binaries, the only place those run on their machines - and it costs nothing once the mirror is public; recommended over keeping more because a job that could publish on the mirror would need a secret there, which is what the mirror should never hold. The mirror's setup - a token with Contents and Workflows write access, the forge's Settings -> Repository -> Mirror settings - is docs/contributing/releasing.md. Releases are not mirrored; GitHub's old seeds release stays as an archive that tools/fetch-seed.sh falls back to.

Security#

• No run of untrusted code on the runner. The runner has Docker, so a job can do almost anything to the runner's machine: a pull request from a fork runs nothing (ci.yml skips every job when the head repository is not this one; a maintainer who wants CI for such a change pushes its branch into the repository), and the forge's own rule that a fork's workflow gets no secrets and no ID token stays as a second line.
• Runners never touch the registry's data. No runner mounts /srv/torb or joins the Docker network of the registry and release-sync; the root server pulls releases and images (section 7.11, "the root server pulls, CI never pushes"), and nothing of CI can write /srv/torb - a compromised job could at worst publish a release, which release-sync refuses unless its signature verifies.
• Tokens are short and narrow. An integration's token lives an hour, admits one repository's named workflows, refs and events, and holds the repository or package permission only. The signing key is the one long-lived secret, read by the jobs that sign.
• Protected refs: main against force pushes and deletion, the tags v* and seeds so that only the owner - and the integration, which acts as the owner - creates them.
• Pinned actions: every uses: names a commit. actions/checkout and actions/cache resolve through the forge's default actions URL (data.forgejo.org mirrors them with the same commits as github.com), the artifact actions are Forgejo's own forks at code.forgejo.org - actions/upload-artifact v4 refuses to run anywhere but github.com.

What the forge's first runs reported (2026-09-27)#

The forge picked up .github/workflows/ci.yml first, since .forgejo/ did not exist yet: every job with a permissions: key was ignored; with the key removed, checkout, the commit check and the change scope passed, the runner reached the forge at https://git.torb.dev, and the bootstrap failed where tools/fetch-seed.sh asked GitHub's private API for the seed (401) - the reason seeds come from the forge now - and actions/upload-artifact v4 refused with "not currently supported on GHES", the reason for Forgejo's forks. The workflows of .forgejo/ pass forgejo-runner validate (runner 13); they had not run on the forge when this was written.

What the first nightly reported (2026-09-28)#

Run 21 of nightly.yml (main at f67f6c34) published nightly-20260928 and failed all three image jobs, for two reasons:

• site and release-sync: no ID token. The key enable-openid-connect stood on the job of images.yml, which the forge drops when it expands a reusable workflow into the calling run (the bullet in "Writing from a workflow" above). It stands at the workflow's top level since, and .forgejo/actions/token names that place when it fails.
• registry: the released torb crashed in the image's build stage, torb build tools/registry/src/main.trb, about three seconds in, with a segmentation fault - the previous nightly's as well. Under gdb in debian:bookworm it died in musl's fmt_fp with the stack pointer 17 KB below the top of the main thread's stack, writing past it: the digit loop of printf("%g") never ended, because its long double was NaN. At fmt_fp's second call the x87 status word held a stack fault and all eight x87 registers were marked in use. The one function of the binary with MMX instructions was the compiler's own lowerComparison (movq (%rsp),%mm0 and two movq2dq), which gcc 13.3 (Ubuntu 24.04, musl-gcc -static, as gates.yml builds the release binary) chose for a 64-bit move and never followed with emms. An MMX instruction marks the x87 stack full, the next x87 load reads NaN, and musl formats every float with long double on the x87 - so any order comparison of a type with Compare (<, >= on a record), followed by printing a float, killed the static binary; glibc's printf does not use the x87, which is why no bootstrapped torb ever showed it, and torb doc std, the site image's one command, never took that path. Fifteen lines reproduce it in torb run. The fix is #pragma GCC target("no-mmx") at the top of runtime/include/torb.h, for gcc on x86-64: it reaches every translation unit the compiler emits and every one of the runtime, whichever script compiles them - build-seed.sh, torb build, a user's program on a musl system - where a flag in one build script would have covered the release binary alone. Built again from the same seed with it, the release binary holds no MMX instruction and builds the registry in debian:bookworm. Three checks keep it: the release-binary step of gates.yml fails on any MMX instruction in the binary, and tools/smoke-test.sh runs that comparison with floats and writes the C of tools/registry with the release binary, before anything is published.