OBELISK.BUILD

Deterministic Build and Execution Fabric

OBELISK is a production-grade build system designed for:

• Deterministic builds with reproducible outputs
• Hermetic action execution with sandboxing
• Content-addressed caching with local and remote backends
• Remote execution with coordinator and workers
• Time-travel debugging with build replay and divergence detection
• Audit-grade tracing of all build operations

Guarantees

OBELISK guarantees:

1. Hermeticity: Actions cannot see undeclared inputs or write outside declared outputs
2. Reproducibility: Same inputs + tools → same outputs (deterministic cache keys)
3. No silent failures: Every cache miss/hit is logged and explainable
4. Stable ordering: All operations are deterministic across platforms
5. Versioned formats: All file formats and protocols are versioned
6. Checksum protection: All data is integrity-checked

Non-Guarantees

OBELISK does NOT guarantee:

1. Compiler determinism unless explicitly pinned and declared
2. Safety of user-provided tools
3. Build optimality (it may not find the fastest build plan)
4. Identical sandbox strength across all platforms

Quick Start

Installation

# Clone the repository
git clone https://github.com/obelisk-build/obelisk.build
cd obelisk.build

# Build with CMake and Ninja
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build

# (Optional) Install
sudo cmake --install build

Basic Usage

# Initialize a new project
obelisk init myproject
cd myproject

# Build all targets
obelisk build

# Run tests
obelisk test

# Generate a build graph visualization
obelisk graph output.dot

Architecture

Action Model

An action is a sealed unit of work with:

1. Declared inputs: files, directories, environment variables, toolchain references
2. Declared outputs: file paths and directory paths
3. Declared command: argv vector (no shell by default)
4. Declared working directory
5. Declared timeout and resource limits
6. Declared sandbox profile
7. Declared cache policy

Cache Model

The cache is content-addressed with keys including:

1. Canonical action spec
2. Hash of all inputs
3. Hash of toolchain artifacts
4. Declared environment
5. Sandbox profile
6. Platform fingerprint (explicit and versioned)

Sandbox Model

Sandbox profiles by platform:

Platform	Profiles Available
Linux	namespaces, chroot+seccomp
macOS	sandbox-init profiles
Windows	job objects, restricted tokens

Remote Execution

• Coordinator: Assigns action nodes to workers
• Workers: Execute actions under sandbox, return outputs
• Protocol: Versioned binary protocol with gRPC

Bundles and Replay

A build bundle is a reproducible capsule containing:

• Action graph
• Canonical specs
• Toolchain references and hashes
• Input manifests and optional blobs
• Trace log
• Platform fingerprint

Bundles enable:

• Offline replay of builds
• Divergence detection
• Time-travel debugging

Repository Layout

obelisk.build/
├── cmd/                    # Command-line tools
│   ├── obelisk/            # Main CLI
│   ├── obeliskd/           # Coordinator daemon
│   ├── obelisk-cache/      # Remote cache server
│   └── obelisk-worker/     # Remote execution worker
├── src/                    # Source libraries
│   ├── core/               # Core types and utilities
│   ├── graph/              # Build graph and scheduler
│   ├── action/             # Action specification and execution
│   ├── sandbox/            # Sandbox adapters
│   ├── cache/              # Content-addressed cache
│   ├── remote/             # Remote cache/execution clients
│   ├── protocol/           # Protocol definitions
│   ├── bundle/             # Build bundles
│   ├── trace/              # Execution tracing
│   └── rules/              # Build rules
├── tests/
│   ├── unit/               # Unit tests
│   ├── integration/        # Integration tests
│   ├── golden/             # Golden file tests
│   ├── sim/                # Deterministic simulation tests
│   └── fuzz/               # Fuzz targets
├── docs/                   # Documentation
├── spec/                   # Formal specifications
└── examples/               # Example projects

CLI Commands

obelisk init <name>              Initialize a new project
obelisk build [targets]          Build targets
obelisk test [targets]           Run tests
obelisk run <target>             Run a target
obelisk query deps <target>      Query dependencies
obelisk graph [output]           Generate graph visualization
obelisk explain <target>         Explain why something rebuilt
obelisk bundle make              Create a build bundle
obelisk bundle replay <bundle>   Replay a build bundle
obelisk cache stats              Show cache statistics
obelisk cache verify             Verify cache integrity
obelisk daemon start             Start the daemon
obelisk worker start             Start a worker

Configuration

OBELISK uses a simple configuration language (OBELISK file):

version = "1.0"

cc_library("mylib") {
    srcs = ["foo.cpp", "bar.cpp"]
    hdrs = ["foo.h", "bar.h"]
    deps = [":otherlib"]
}

cc_binary("myapp") {
    srcs = ["main.cpp"]
    deps = [":mylib"]
}

Contributing

See CONTRIBUTING.md for guidelines.

---

• Documentation: docs/
• Changelog: CHANGELOG.md
• Contributing: CONTRIBUTING.md
• Security Policy: docs/SECURITY.md
• Issue Tracker: GitHub Issues
• Release Notes: RELEASE.md

License

Apache-2.0 OR MIT - See LICENSE for details.