basin skill

safe

This skill helps you navigate the basin codebase, optimize workflows, and understand its multi-engine storage and Sigil language integrations.

npx playbooks add skill plurigrid/asi --skill basin

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.5 KB

---
name: basin
description: "Basin unified storage platform. Rust monorepo with Sigil language, GPU pipelines, and multi-engine storage. Use when working in the basin codebase."
metadata:
  trit: 1
  version: "0.1.0"
  bundle: infrastructure
---

# Basin Skill

**Repo**: `/Users/alice/worlds/b/basin` (jj + [email protected]:zubyul/basin.git)
**Full context**: `docs/BASIN_CONTEXT_20K.md`

## Build & Test

```bash
cd /Users/alice/worlds/b/basin
graft build --release
graft test --workspace          # uses nextest
graft run -p basin --release    # run basind
```

## Repo Layout

```
foundation/    # Zero-dep crates: core-traits, basin-error, basin-par
engines/       # scree (hash), steel (btree), shale (LSM), sonar (HNSW)
crates/        # Core: slate, spiel, magma, shore, shoal, dgx-sim
modules/       # Protocol modules (dynamic loading)
apps/          # basin-redis, basin-s3, etc.
products/      # Unified binaries: basin, yard, graft-daemon
sigil/         # Sigil language + compiler
tools/         # refactor, forge, semantic-git
warehouse_map/ # DGX fabric topology, Modelica sim, network SVGs
cli/           # basin-cli, basin-shell
```

## Engines

| Engine | Type | Use |
|--------|------|-----|
| Scree | Hash | Hot L0, O(1), 3M+ ops/s |
| Steel | B-tree | Ordered L1, range scans |
| Shale | LSM | Cold storage, write-heavy |
| Sonar | HNSW | ANN search |

CAS integrated into Slate via `SlateContentStore`.

## Sigil Language

```bash
graft run --bin sigil --features rust-codegen -- file.sigil --gpu=compile
graft run --bin sigil --features rust-codegen -- file.sigil --gpu=run
graft run --bin sigil --features rust-codegen -- --gpu=info
```

## DGX Simulator

```bash
graft test -p dgx-sim           # test cycle-level sim
graft bench -p dgx-sim          # benchmarks
```

Crate at `crates/dgx-sim/` — cycle-level GB10 simulator with tropical semiring cost algebra.

## Warehouse Map

`warehouse_map/` contains the physical DGX Spark cluster topology:
- 11 DGX Spark machines via CRS812 switch (1.2 Tb/s fabric)
- `Warehouse.mo` — Modelica acausal model (WiFi L1 + fabric L2)
- `simulate.py` — DAE solver outputting to DuckDB
- `WarehouseNetwork.svg` — integrated topology diagram
- `warehouse.duckdb` — all simulation + tailscale mesh data

## Version Control

```bash
cd /Users/alice/worlds/b/basin
jj st                              # status
jj describe -m "msg"               # commit message
jj git push --bookmark main        # push
jj git fetch && jj rebase -d main@origin  # pull + rebase
```

Overview

This skill helps developers navigate and work effectively in the Basin unified storage platform codebase. It summarizes repo layout, build/test commands, engines, Sigil language usage, DGX simulator components, and version-control workflows. Use it as a quick reference when developing, testing, or extending Basin components.

How this skill works

The skill inspects the project structure and key developer workflows, providing concise commands and locations for builds, tests, simulators, and language tooling. It highlights engine types and their intended workloads, where to find Sigil compiler targets, and where physical topology and simulation artifacts live. It also captures recommended version-control commands and packaging entry points for the main binaries and apps.

When to use it

Onboard to the Basin Rust monorepo and learn the top-level layout
Build, test, or run Basin binaries and Sigil GPU workflows
Choose the right storage engine for a workload (hash, b-tree, LSM, ANN)
Run or extend the DGX fabric simulator and examine warehouse topology
Integrate or debug apps, modules, or unified binaries like basin and yard

Best practices

Use graft commands from the repo root for reproducible builds and tests
Pick engines by access pattern: Scree for hot O(1) workloads, Steel for ordered scans, Shale for write-heavy cold storage, Sonar for ANN
Keep Sigil GPU workflows in the sigil/ toolchain and use rust-codegen feature for native paths
Run dgx-sim tests/benchmarks in crates/dgx-sim for cycle-level validation before hardware runs
Store physical topology and simulation outputs in warehouse_map/ and use the provided scripts and DuckDB for analysis

Example use cases

Compile and run basind in release mode for integration validation
Develop a new engine module under engines/ and run workspace tests with nextest
Compile Sigil programs to GPU code and run compiled kernels via graft run --bin sigil
Simulate DGX fabric power and network behavior using Warehouse.mo and simulate.py, then query outputs in warehouse.duckdb
Prototype a new protocol module in modules/ and dynamically load it into a unified binary for manual testing

FAQ

Where are the core crates and zero-dependency libraries located?

Core zero-dep crates live in foundation/, and key core crates are under crates/ (slate, spiel, magma, etc.).

How do I run Sigil GPU compile and run workflows?

Use graft run --bin sigil with --features rust-codegen and flags: file.sigil --gpu=compile, --gpu=run, or --gpu=info.