traits.build

CLI & HTTP

sys.cli parses args, kernel.serve starts actix-web. Every sys.* trait is a direct subcommand.

Dispatcher

Resolves paths, validates & coerces arguments, dispatches to compiled Rust trait functions.

Registry

Concurrent DashMap of .trait.toml definitions. Loads from disk + compiled builtins. Hot-reloadable.

Interface System

provides / requires / bindings. Per-call overrides, global bindings, or auto-discovery.

Plugin Loader

kernel.dylib_loader discovers cdylib .dylib plugins at startup for dynamic trait extensions.

Type System

int, float, string, bool, bytes, any, list<T>, map<K,V>, T? — validated at dispatch time.

Why Traits?

🚀

Single binary, zero runtime

Every trait compiles directly into the binary via build.rs. No containers, no workers, no runtime dependencies. One ~2 MB executable does everything.

⚙️

Self-describing kernel

Registry, dispatcher, config, CLI, and HTTP server are all traits. Call kernel.main to see every module, interface, and bootstrap step.

🔌

CLI + REST, one trait

Every trait is callable via REST API (POST /traits/ns/name) and CLI (traits name args). No glue code needed.

🔗

Interface wiring

Traits declare provides, requires, and bindings in TOML. Resolution: per-call overrides → global bindings → auto-discover.

🧩

Build-time codegen

build.rs discovers all .trait.toml files, generates dispatch tables, embeds definitions, auto-bumps versions and checksums.

📦

cdylib plugins

Extend at runtime with .dylib shared libraries. The kernel discovers and loads them at startup via kernel.dylib_loader.

Built-in traits

Trait	What it does
kernel.main	Entry point, bootstrap, compiled module list, interface introspection
kernel.dispatcher	Path resolution, argument validation & coercion, compiled dispatch
kernel.registry	Load .trait.toml definitions, DashMap lookup, interface resolution
kernel.config	traits.toml parsing, env var overrides, runtime config
kernel.serve	Start the actix-web HTTP server with CORS & SSE streaming
kernel.dylib_loader	Discover and load cdylib .dylib plugins at startup
kernel.types	TraitValue, TraitType, type parsing (list<map<string,int>>)
kernel.globals	OnceLock statics: REGISTRY, CONFIG, TRAITS_DIR, HANDLES
kernel.call	Call any trait by dot-notation path (inter-trait dispatch)
kernel.plugin_api	C ABI export macro for cdylib trait plugins
kernel.reload	Hot-reload the trait registry from disk
sys.cli	Clap parsing, subcommand dispatch, arg coercion, pipe support
sys.registry	Read API: list, info, tree, namespaces, count, search
sys.checksum	SHA-256 checksums for strings, I/O pairs, and signatures
sys.version	Generate YYMMDD date-format versions
sys.snapshot	Snapshot a trait version (YYMMDD or YYMMDD.HHMMSS)
sys.test_runner	Run .features.json tests — dispatch examples + shell commands
sys.list	List all registered traits
sys.info	Show detailed trait metadata and signatures
sys.ps	List running background traits with process details
www.traits.build	This landing page
www.admin	Admin dashboard with deployment controls (Basic Auth)
www.admin.deploy	Deploy to Fly.io
www.admin.scale	Scale Fly.io machines up or down
www.admin.destroy	Destroy Fly.io machines

Interface system

# kernel/main/main.trait.toml
[trait]
description = "Binary entry point"

# Declare what this trait needs
[requires]
dispatcher = "kernel/dispatcher"
registry   = "kernel/registry"
config     = "kernel/config"

# Wire each slot to a concrete provider
[bindings]
dispatcher = "kernel.dispatcher"
registry   = "kernel.registry"
config     = "kernel.config"

Resolution chain

per-call overrides → global bindings → caller [bindings] → auto-discover

Trait definition format

# traits/sys/checksum/checksum.trait.toml
[trait]
description = "SHA-256 checksums"
version     = "v260320.142947"
author      = "system"
tags        = ["system", "crypto"]
provides    = ["sys/checksum"]

[signature]
params = [
  { name = "mode",  type = "string", description = "hash | io_pairs | signature" },
  { name = "input", type = "any",    description = "Data to checksum" },
]

[signature.returns]
type = "string"
description = "Hex-encoded SHA-256 hash"

[implementation]
language = "rust"
source   = "builtin"    # compiled directly into the binary
entry    = "checksum"

int

float

string

bool

bytes

any

list<T>

map<K,V>

T? (optional)

handle

Quick start

# CLI — every sys.* trait is a direct subcommand
$ traits serve --port 8090
$ traits list
$ traits checksum hash "hello"
"2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
$ traits info sys.checksum
$ traits test_runner '*'       # run all .features.json tests
$ echo hello | traits checksum hash  # pipe support

# REST API — POST /traits/{namespace}/{name}
$ curl -X POST https://traits.build/traits/sys/checksum \
    -H 'Content-Type: application/json' \
    -d '{"args": ["hash", "hello"]}'

# List everything
$ curl https://traits.build/traits/sys/list

# Health check
$ curl https://traits.build/health

How it works

# 1. Define a trait (TOML + Rust source)
traits/sys/checksum/checksum.trait.toml
traits/sys/checksum/checksum.rs

# 2. build.rs discovers it automatically
#    - Embeds the TOML via include_str!
#    - Generates mod declarations
#    - Creates dispatch_compiled() match arms
#    - Validates checksums, bumps versions

# 3. cargo build produces a single binary
$ cargo build --release
#    target/release/traits (~2 MB)

# 4. Run it anywhere
$ ./traits serve --port 8090
#    25 traits loaded, 0 workers, 0 dependencies

Architecture