Traits — Kernel

A Rust-native trait platform. Traits are typed, composable function objects defined in .trait.toml files with companion Rust source. All 26 traits compile directly into a single traits binary — zero worker processes, zero HTTP overhead for inter-trait calls. Every trait is callable via CLI, REST API, or internal dispatch.

Live: traits.build
Repo: github.com/kilian-ai/traits.build

Traits (26)

kernel.* — Core runtime (11)

sys.* — System utilities (9)

www.* — Web interface (6)

Architecture

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  CLI (main)  │────▶│  Dispatcher  │────▶│  Compiled    │
│  call/serve  │     │  resolve +   │     │  trait fns   │
│  list/info   │     │  coerce args │     │  (Rust)      │
└──────────────┘     └──────────────┘     └──────────────┘
                            │
                     ┌──────▼──────┐
                     │  Registry   │
                     │  (DashMap)  │
                     └─────────────┘

• Entry point (src/main.rs = traits/kernel/main/main.rs) — binary entry, bootstrap() loads config → registry → dylibs → resolves interfaces → creates Dispatcher. Declares [requires] for dispatcher, registry, config, globals, dylib_loader — all resolved through the interface system
• CLI (traits/sys/cli/cli.rs) — clap parsing, trait dispatch, arg coercion, result formatting. Any unknown subcommand is tried as sys.{name} then kernel.{name}
• Dispatcher (traits/kernel/dispatcher/) — resolves trait paths, validates/coerces arguments, dispatches to compiled modules
• Registry (traits/kernel/registry/) — loads .trait.toml definitions from disk + compiled builtins, concurrent DashMap storage, interface resolution
• Serve (traits/kernel/serve/) — actix-web HTTP server, runs as a background trait. Routes URL paths to www/webpage interface providers via keyed bindings
• Dylib loader (traits/kernel/dylib_loader/) — optional dynamic library loading for external trait plugins
• Types (traits/kernel/types/) — TraitValue, TraitEntry, TraitSignature, wire protocol types

CLI

Every sys.* trait is available as a direct subcommand — no call sys. prefix needed:

# Start the server (default when no subcommand given)
traits serve --port 8090

# List all traits
traits list

# Show trait info
traits info sys.checksum

# Run tests
traits test_runner '*'

# Compute a checksum
traits checksum hash hello

# Snapshot a trait version
traits snapshot sys.version

The call subcommand dispatches any trait by full path (useful for non-sys namespaces):

traits call kernel.serve 8090

Arguments are positional and mapped to params via the CLI's inline arg parser. Pipe input is supported for params with pipe = true:

echo hello | traits checksum hash

REST API

All traits are callable over HTTP when the server is running:

# Call a trait
curl -X POST http://127.0.0.1:8090/traits/sys/checksum \
  -H 'Content-Type: application/json' \
  -d '{"args": ["hash", "hello"]}'

# List traits
curl http://127.0.0.1:8090/traits/sys/list

# Reload registry
curl -X POST http://127.0.0.1:8090/traits/kernel/reload

# SSE streaming
curl 'http://127.0.0.1:8090/traits/sys/list?stream=1'

# Health check
curl http://127.0.0.1:8090/health

Testing

Every trait has a .features.json file with example tests (internal dispatch) and command tests (shell):

# Run all tests
traits test_runner '*'

# Run tests for a specific trait
traits test_runner sys.checksum

# Verbose output
traits test_runner '*' true

Trait Definition Format

Each trait lives in traits/{namespace}/<name>/ with:

• <name>.trait.toml — metadata, params, returns, implementation pointer, interfaces
• <name>.rs — Rust source (compiled into the binary via build.rs)
• <name>.features.json — test cases (optional)
• <name>.md — documentation (optional)

Example call.trait.toml:

[trait]
description = "Call another trait by dot-notation path"
version = "v260322"
author = "system"
tags = ["system", "meta", "dispatch"]
provides = ["kernel/call"]

[signature]
params = [
  { name = "trait_path", type = "string", description = "Dot-notation trait path" },
  { name = "args", type = "list<any>", description = "Arguments forwarded to the target trait", optional = true }
]

[signature.returns]
type = "any"
description = "Result from the called trait"

[implementation]
language = "rust"
source = "builtin"
entry = "call"

File Layout

src/
  main.rs              # Binary entry point (Cargo.toml target)
  main.trait.toml      # Trait definition for kernel.main

traits/kernel/
  main/                # Bootstrap, trait_exists(), introspection
  call/                # Inter-trait dispatch by dot-notation path
  config/              # Server configuration (traits.toml + env vars)
  dispatcher/          # Path resolution, arg validation, compiled dispatch
  dylib_loader/        # Dynamic library trait plugins
  globals/             # Global state (OnceLock registry, config, traits dir)
  plugin_api/          # C ABI export macro for cdylib plugins
  registry/            # Trait registry (load, store, lookup, interface resolution)
  reload/              # Hot-reload registry from disk
  serve/               # HTTP API server (actix-web)
  types/               # Core types (TraitValue, TraitEntry, signatures)

traits/sys/
  checksum/            # SHA-256 hashing primitives
  cli/                 # CLI clap parsing, dispatch routing
  info/                # Trait introspection (delegates to registry)
  list/                # Trait listing (delegates to registry)
  ps/                  # Background trait process listing
  registry/            # Registry read API (list, info, tree, search)
  snapshot/            # YYMMDD version snapshots
  test_runner/         # Test discovery and execution
  version/             # Version generation

traits/www/
  traits/build/        # Landing page (www.traits.build)
  admin/               # Admin dashboard
    deploy/            # Fly.io deployment
    fast_deploy/       # Fast binary deploy via sftp
    scale/             # Fly.io machine scaling
    destroy/           # Fly.io machine destruction

Interface System

Traits declare dependencies through interfaces — named contracts that are provided, required, and bound entirely within .trait.toml files. There are no separate interface definition files.

How it works

1. Provide — a trait declares what interfaces it satisfies via provides in [trait]:

   [trait]
   provides = ["kernel/dispatcher"]
   

2. Require — a consuming trait declares [requires] with a logical key mapped to an interface name:

   [requires]
   dispatcher = "kernel/dispatcher"
   

3. Bind — the same trait provides default wiring in [bindings], mapping the key to a concrete trait:

   [bindings]
   dispatcher = "kernel.dispatcher"
   

4. Resolve at runtime — the registry resolves interfaces through a priority chain:

   • Per-call overrides (highest priority)
   • Global bindings
   • Caller's [bindings]
   • Auto-discover (find providers, pick by priority)

URL-keyed bindings

kernel.serve uses interface keys as URL paths, binding each route to a www/webpage provider:

[requires]
"/" = "www/webpage"
"/admin" = "www/webpage"
dispatcher = "kernel/dispatcher"

[bindings]
"/" = "www.traits.build"
"/admin" = "www.admin"
dispatcher = "kernel.dispatcher"

Current interfaces

Build System

build.rs auto-discovers all traits and generates Rust code at compile time:

• builtin_traits.rs — embeds all .trait.toml definitions via include_str!
• compiled_traits.rs — module declarations + dispatch_compiled() match table
• kernel_modules.rs — crate-level pub mod declarations for kernel subdirectories
• cli_formatters.rs — optional CLI output formatters from *_cli.rs companion files

Version is auto-computed as vYYMMDD (or vYYMMDD.HHMMSS for same-day rebuilds). Source file checksums are computed and written back to each .trait.toml.

cargo build --release
./target/release/traits serve --port 8090

Deployment

Deployed on Fly.io:

cd path/to/traits.build
docker buildx build --platform linux/amd64 -t registry.fly.io/your-fly-app:latest .
fly deploy --now --local-only --image registry.fly.io/your-fly-app:latest

See docs/deploy.md for details, docs/release.md for GitHub releases.