First-Party Packages#

Status: decided 2026-09-29; torb/sql 0.1.0 and torb/postgres 0.1.0 built and tested, torb/redis 0.1.0 published — the owner asked on 2026-09-28 for packages the project offers itself that do not belong in std: adapters for databases, key-value stores and document stores, "everything TorbScript will surely need for full-scale development". This record decides the vendor they are published under, the line between them and std, how their repositories look, and the order they come in; section 6 and 7 record the first two as built, and section 8 lists what std lacks for all of them, as input for the rounds of std. Nothing here is published yet except torb/redis.

A first-party package is an adapter to a system outside the program, published by the project under the owner torb, in a repository of its own, with its own version. std stays what every program may need and what reaches no service; the moment a package speaks the protocol of somebody else's server, it leaves std for torb/*, where it can follow that server's releases instead of the language's.

   a program          use Pool from "torb/sql"          use Postgres from "torb/postgres"
       │                          │                                │
   torb/*             torb/sql ── values, rows, errors, Pool, Transaction, the traits a driver implements
   (git.torb.dev/torb, │           ▲            ▲            ▲
    packages.torb.dev) │      torb/postgres  torb/mysql  torb/sqlite          torb/redis   torb/mongodb   torb/s3
       │               │           │            │            │                    │            │            │
   std                 std/network, std/tls, std/digest, std/binary, std/encoding, std/uri, std/storage, std/task

Contents#

• 1. Goals
• 2. The vendor — torb, and the three it was weighed against
• 3. The line between std and torb/*
• 4. Repository conventions — template, layout, CI, publishing, versions, support
• 5. The order — the packages, with reasons and what each waits for
• 6. torb/sql, as built
• 7. torb/postgres, as built
• 8. What std is missing — the gaps, precisely, as input for rounds of std
• 9. What building them found in the toolchain
• 10. Slices
• 11. Open

1. Goals#

1. A program talks to the services it runs against without leaving TorbScript: Postgres, MySQL, SQLite, Redis, MongoDB, object storage, a message broker, mail - each one import away, each one idiomatic: errors as values, Tasks for everything that waits, full words in every name.
2. Pure TorbScript over std, no C, until foreign is decided (RELEASE.md section 2; open, see FOREIGN.md section 5.3): a package of the registry carries source and nothing else (RELEASE.md section 7.2), so a driver is the wire protocol written out, like Go's pgx or Rust's sqlx, not a binding to libpq.
3. One shape per kind of service. Every SQL driver implements the traits of torb/sql, so the pool, the transactions, the rows and the errors are written once and a program changes databases by changing a line; the connection string is a URI whose scheme chooses the driver (URI.md section 11).
4. Each package follows its service, not the language: its own semantic version and cadence, a support policy that names the versions of the service it is tested against, and CI against the real service in a container.
5. What the packages need from std is found by building them, and written down (section 8), rather than guessed: a gap is closed in std once two packages worked around it.

2. The vendor#

Decision: the owner torb — torb/postgres, torb/redis, torb/sql — and the repositories in the organisation torb of git.torb.dev, where the path of a repository is the name of its package (git.torb.dev/torb/postgres).

The toolchain's packages stay torbscript/*, and std/* stays the toolchain's own: three owners, three meanings - std comes with torb and needs no line in project.trb, torbscript is the toolchain, torb is what the project publishes for programs to depend on.

3. The line between std and torb/*#

Decision: std holds what every program may need, reaches no external service, and follows the language's release and its compatibility promise; torb/* holds adapters to external systems, each with its own semantic version and cadence. One question decides a case: does the package speak the protocol of a server somebody else writes? If it does, its correctness depends on that server's releases, its tests need that server, and its version has to move with it - so it cannot ride the language's one version number (RELEASE.md section 3).

What that puts where:

A package moves from torb/* into std only when the line moves: if a protocol becomes something every program needs and a service nobody runs (HTTP once was a service), it is proposed for std with the reasons, and torb/* keeps a last version that re-exports it. Nothing moves the other way after 1.0: that would break a promise.

URI.md's Connection, Connect and Cache were written out "so that the ecosystem converges on one spelling" and left out of std. torb/sql takes the first two, shaped for SQL (section 6): its Connection has the query surface URI.md said a generic one cannot carry, because every SQL database has the same one. Cache waits for a second key-value driver next to torb/redis; until then torb/redis has its own types.

4. Repository conventions#

Every package is its own repository in the organisation torb of git.torb.dev, made from the package template (torb/package-template, mirrored to GitHub): the template's CI, its trusted publishing on a tag v*, its MIT license, its README skeleton.

torb/postgres/
├─ project.trb           name "torb/postgres", version, description, license "MIT", repository, language, authors
├─ project.lock.trb      committed: the dependencies a check resolves against
├─ src/lib.trb           the library; every public name exported from here, with a doc comment
├─ tests/unit/           no service: the codec, the types, a double of the server on loopback
├─ tests/integration/    against the real service, in a container
├─ tests/fixtures/       certificates and the like for the tests
├─ scripts/<service>.sh  starts the service in Docker for a developer, the same image CI uses
├─ examples/             programs a reader runs by hand
├─ README.md             what it is, connecting, the type mapping, what is not supported, developing, publishing
├─ LICENSE               MIT
├─ .forgejo/workflows/   ci.yml, publish.yml
└─ .github/workflows/    the same, for the mirror

The support policy: a package supports the versions of its service that the service's own project supports, and CI runs against the newest; the README says which. For the first packages:

5. The order#

Decision: the SQL foundation and Postgres first, then the rest of what a web service stands on, in this order. Each row says why it is where it is, and what it waits for.

6. torb/sql, as built#

What it is: the layer Go's database/sql is, with the traits Rust's sqlx has, in the shape URI.md section 11 wrote out. It imports std/uri, std/encoding, std/task and std/time and reaches nothing: its publish summary said clock, only because Timestamp lives in std/time, until gap 10 of section 8 was closed.

Decisions, and what they were weighed against:

Tested: 46 tests in both back ends - the values and their texts, Date and Uuid, rows read by name, as types and whole, the failures, and the pool, transactions and the registry against a double of a driver (tests/pool.test.trb), which is also the smallest complete example of a driver.

7. torb/postgres, as built#

What it is: a driver in TorbScript over std/network and std/tls, no C, about 2 500 lines. The protocol 3.0 of the Postgres manual's "Frontend/Backend Protocol", message by message.

Decisions:

Tested, with Postgres in Docker (postgres:17-alpine, started by scripts/postgres.sh with md5 for host connections and TLS with the test certificate): 53 unit tests - the codec, the types, the connection string, the cryptography against RFC 1321, 4231, 7914 and 7677, and a double of a server on loopback for trust, the password in the clear, md5, refusals, TLS through the TLS request, errors, notices, notifications and a connection that breaks - and 65 integration checks against the real server: SCRAM and md5 roles, a wrong password, a database that does not exist, TLS with the root trusted and without, every type both ways, a timestamp in another session zone, counts, a script, unique, not-null and foreign-key violations with their constraint, a syntax error's position, COPY refused, 20 000 rows, a value of a million bytes, notices, commit, rollback, a failed and an abandoned transaction, three statements at once through a pool of two, a pooled transaction, the registry, LISTEN/NOTIFY between two sessions, and a statement cut off by a timeout. All of it passes in the VM and natively. The CI's service container runs the same suite without TLS.

8. What std is missing#

Found by building torb/sql and torb/postgres, and by reading what the packages after them need. Each gap names who needs it and what is done in its place until then.

What the list says, in short: the crypto primitives (1 to 6) block the most packages; the wall clock and the calendar (9 to 11) are needed by every driver and by everything that signs; the stream and transport helpers (14 to 17) are written three times already.

Closed on 2026-09-29: 5, 9 and 10. The randomness (Entropy) went to std/os rather than std/random, because the system's entropy is a capability and std/random has none (RANDOM.md section 4); the wall clock is Clock.timestamp(), because reading it is the capability and Clock is where every reading is; and a Timestamp in a signature reaches nothing, because the capability summary now decides by each imported name instead of by package. torb/postgres can take its nonce from Entropy.bytes 18 instead of nine DNS identifiers.

9. What building them found in the toolchain#

Each with a program that shows it, kept beside the packages until the coordinator files them:

10. Slices#

The trusted publishers each package needs before its first tag (docs/contributing/releasing.md step 7, sent by an owner of torb):

PUT https://packages.torb.dev/api/1/packages/torb/sql/trusted-publishers
{"publishers":[{"repository":"git.torb.dev/torb/sql","workflow":"publish.yml","ref":"refs/tags/v*"},
               {"repository":"TorbScript/sql","workflow":"publish.yml","ref":"refs/tags/v*","environment":"release"}],
 "required":true}

PUT https://packages.torb.dev/api/1/packages/torb/postgres/trusted-publishers
{"publishers":[{"repository":"git.torb.dev/torb/postgres","workflow":"publish.yml","ref":"refs/tags/v*"},
               {"repository":"TorbScript/postgres","workflow":"publish.yml","ref":"refs/tags/v*","environment":"release"}],
 "required":true}

The second entry of each is the GitHub mirror, where one exists under that name; a Forgejo publisher names no environment, because Forgejo's tokens carry none.

11. Open#

• A generic Cache trait (URI.md section 11): with torb/redis there is one driver; a second (Memcached, or a MemoryCache that is more than a test double) decides whether the trait goes to torb/cache or waits.
• sslmode=require: libpq's require encrypts without checking the certificate, and a program ported from libpq may rely on that against a server with a self-signed certificate. This driver checks, because std/tls offers no way not to; trusting the server's own certificate in TlsSettings.trusted is the way through. Whether std/tls should offer pinning a certificate's hash instead is gap 18's question.