Lib.rs

The .bit language toolkit — parse, validate, render, store, and convert structured documents.

What is .bit?

.bit is a structured document language for defining entities, tasks, flows, and schemas. Think of it as a middle ground between Markdown (human-readable) and JSON (machine-processable) — with first-class support for state machines, typed schemas, and ternary validation.

# Project Setup

define:@User
    name: ""!
    email: ""!
    role: :admin/:editor/:viewer!

mutate:@User:alice
    name: "Alice Chen"
    email: "alice@example.com"
    role: :admin

## Tasks
    [x] Define user schema
    [!] Add authentication flow
    [!] Write API endpoints :@alice

    flow:onboarding
        draft --> review --> approved

Why .bit?

Install

CLI

# Cargo
cargo install bit-lang-cli

# Homebrew (coming soon)
brew install zaius-labs/tap/bit-lang

Rust Library

[dependencies]
bit-lang-core = "0.1"

JavaScript / TypeScript (WASM)

npm install bit-lang

Python

pip install bit-lang

Quick Start

1. Create a .bit file

bit init my-project
cd my-project

This creates a starter project with schema.bit (the language reference, embedded in every bitstore as @_system:schema).

2. Define entities and tasks

Create users.bit:

# Users

define:@User
    name: ""!
    email: ""!
    role: :admin/:editor/:viewer!
    active: true?

mutate:@User:alice
    name: "Alice Chen"
    email: "alice@example.com"
    role: :admin

mutate:@User:bob
    name: "Bob Smith"
    email: "bob@example.com"
    role: :editor

## Onboarding
    [x] Set up user schema
    [!] Add authentication flow
    [!] Write API endpoints

3. Parse and explore

# Parse to JSON AST
$ bit parse users.bit | jq '.nodes | length'
4

# Format with consistent style
$ bit fmt users.bit --write

# Validate against schema
$ bit validate users.bit

# Convert JSON to .bit
$ echo '{"Product": {"name": "Widget", "price": 9.99}}' | bit convert - --from json
define:@Product
    name: "Widget"
    price: 9.99

4. Store and expand

# Pack .bit files into a compressed store
$ bit collapse ./my-project
Collapsed 3 files into my-project.bitstore

# Expand back to editable files
$ bit expand my-project.bitstore --output ./working
Expanded 3 files to ./working

# Check for drift
$ bit status my-project.bitstore ./working
No changes

Architecture

┌─────────────────────────────────────────────────────┐
│                   bit-lang ecosystem                 │
├─────────────┬───────────┬───────────┬───────────────┤
│  bit-lang   │ bit-lang  │ bit-lang  │  your app     │
│  cli (bit)  │ (PyO3)    │ (WASM)    │  (Rust lib)   │
├─────────────┴───────────┴───────────┴───────────────┤
│                  bit-lang-core (Rust)                │
│  ┌────────┐ ┌────────┐ ┌──────────┐ ┌────────────┐ │
│  │ Parser │ │   IR   │ │Interpret │ │  Validate  │ │
│  │  5.7K  │ │  1.4K  │ │   0.7K   │ │    1.0K    │ │
│  └────┬───┘ └────┬───┘ └────┬─────┘ └─────┬──────┘ │
│  ┌────┴───┐ ┌────┴───┐ ┌────┴─────┐ ┌─────┴──────┐ │
│  │ Lexer  │ │ Schema │ │  Gates   │ │  Checks    │ │
│  │  0.6K  │ │  0.4K  │ │  0.7K    │ │    1.1K    │ │
│  └────────┘ └────────┘ └──────────┘ └────────────┘ │
│  ┌────────┐ ┌────────┐ ┌──────────┐ ┌────────────┐ │
│  │ Render │ │ Format │ │  Query   │ │  Convert   │ │
│  │  1.3K  │ │  1.1K  │ │  0.5K    │ │   (J/M/T)  │ │
│  └────────┘ └────────┘ └──────────┘ └────────────┘ │
├─────────────────────────────────────────────────────┤
│              bit-lang-store                          │
│                                                     │
│  ┌─────────────────────────────────────────────┐    │
│  │         Page-Based Database Engine           │    │
│  │                                             │    │
│  │  ┌───────┐ ┌────────┐ ┌──────┐ ┌────────┐  │    │
│  │  │ Pager │ │ B-Tree │ │Tables│ │ Query  │  │    │
│  │  │ cache │ │ search │ │entity│ │ engine │  │    │
│  │  │ flush │ │ insert │ │task  │ │ filter │  │    │
│  │  │ free  │ │ delete │ │flow  │ │ sort   │  │    │
│  │  │ list  │ │ scan   │ │blob  │ │ limit  │  │    │
│  │  └───────┘ └────────┘ └──────┘ └────────┘  │    │
│  │                                             │    │
│  │  4KB pages · B-tree indexes · blake3 hashes │    │
│  │  Single file · Zero config · Instant queries│    │
│  └─────────────────────────────────────────────┘    │
│                                                     │
│  ┌─────────────────────────────────────────────┐    │
│  │         Store Intelligence (zero-dep)        │    │
│  │                                             │    │
│  │  schema inference · predictive autocomplete  │    │
│  │  drift detection · NL queries · BM25 search  │    │
│  │  entity linking · pattern detection          │    │
│  │  schema evolution · composite scoring        │    │
│  │                                             │    │
│  │  opt-in: vector search · anomaly · classify  │    │
│  └─────────────────────────────────────────────┘    │
│                                                     │
│  collapse ↔ expand ↔ query ↔ mutate ↔ status       │
└─────────────────────────────────────────────────────┘

CLI Reference

Core Commands

Store Commands

Database Commands

Utility Commands

All commands support - for stdin and output JSON to stdout.

SDK Usage

Rust

use bit_core::*;

// Parse
let doc = parse_source("define:@User\n    name: alice").unwrap();

// Render back
let text = render_doc(&doc);

// Format
let formatted = fmt("# Title\n[!] Task").unwrap();

// Convert from JSON
let doc = from_json(r#"{"User": {"name": "alice"}}"#).unwrap();
let bit_text = render_doc(&doc);

// Build index
let idx = build_index(&doc);

// Validate
let schemas = load_schemas(&["define:@User\n    name: \"\"!\n    email: \"\"!"]).unwrap();
let result = validate_doc(&doc, &schemas);

JavaScript / TypeScript

import { parse, fmt, fromJson, fromMarkdown, toJson } from 'bit-lang';

// Parse .bit to AST
const doc = parse('define:@User\n    name: alice');

// Format
const formatted = fmt('# Title\n[!] Task');

// Convert
const bitText = fromJson('{"User": {"name": "alice"}}');
const json = toJson('define:@User\n    name: alice');

Python

import bit_lang

# Parse .bit to JSON AST
ast = bit_lang.parse('define:@User\n    name: alice')

# Format
formatted = bit_lang.fmt('# Title\n[!] Task')

# Convert
bit_text = bit_lang.from_json('{"User": {"name": "alice"}}')
json_str = bit_lang.to_json('define:@User\n    name: alice')

.bit Language Reference

Syntax Overview

┌─────────────────────────────────────────────┐
│  .bit Document Structure                    │
├─────────────────────────────────────────────┤
│                                             │
│  # Group (depth 1)                          │
│  ## Subgroup (depth 2)                      │
│                                             │
│  [!] Pending task                           │
│  [x] Completed task                         │
│  [o] In-progress task                       │
│  [A!] Labeled task                          │
│                                             │
│  define:@Entity                             │
│      field: value                           │
│      required_field: ""!                    │
│      int_field: 0#                          │
│      float_field: 0.0##                     │
│      bool_field: true?                      │
│      timestamp: ""@                         │
│      enum: :a/:b/:c!                        │
│      list: []                               │
│      json: {}                               │
│      relation: ->@Other                     │
│                                             │
│  mutate:@Entity:id                          │
│      field: new_value                       │
│                                             │
│  flow:name                                  │
│      draft --> review --> approved           │
│                                             │
│  gate:requirement                           │
│      {condition_met}                        │
│                                             │
└─────────────────────────────────────────────┘

Field Sigils

Task Markers

See schema.bit (embedded in every bitstore as @_system:schema) for the complete grammar specification.

Lesson Book

Comprehensive guides and examples for learning .bit:

• Getting Started — Install, first .bit file, basic CLI usage
• Entities & Schemas — Define typed entities, field sigils, mutations
• Tasks & Flows — Task tracking, state machines, flow transitions
• Gates & Validation — Ternary logic, gate conditions, check suites
• Store & Expand — .bitstore format, pack/unpack workflow
• Converting Formats — JSON ↔ .bit, Markdown → .bit, TOML → .bit
• Harness Integration — Watch mode, apply to Claude Code and other harnesses
• Advanced Patterns — Nested entities, computed fields, query expressions
• How the Bitstore Engine Works — Pages, B-trees, queries: building a database from scratch
• Store Intelligence — Schema inference, drift detection, NL queries, pattern detection, and more

.bitstore Engine

The .bitstore file is a page-based database — like SQLite for .bit documents. Single file, zero config, instant queries.

┌──────────────────── .bitstore ────────────────────┐
│                                                    │
│  Page 0: Header                                    │
│  ┌──────────────────────────────────────────────┐  │
│  │ BITS │ 4096 │ roots: entity,task,flow,    │  │
│  │      │      │ schema,blob │ change_ctr      │  │
│  └──────────────────────────────────────────────┘  │
│                                                    │
│  Pages 1..N: B-tree nodes                          │
│  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐             │
│  │entity│ │ task │ │ flow │ │ blob │  ...         │
│  │B-tree│ │B-tree│ │B-tree│ │B-tree│              │
│  └──────┘ └──────┘ └──────┘ └──────┘             │
│                                                    │
│  4KB pages · B-tree indexes · O(log n) lookups     │
└────────────────────────────────────────────────────┘

How it works

• Collapse (bit collapse): parses every .bit file, extracts entities/tasks/flows/schemas, inserts into B-tree indexes, stores raw file blobs. One file becomes a queryable database.
• Query (bit query store "@User where role=admin"): seeks B-tree directly — reads ~3 pages instead of decompressing everything.
• Mutate (bit insert/update/delete): writes directly to the B-tree. No expand-edit-collapse cycle needed.
• Expand (bit expand): reads blobs from the B-tree, writes .bit files back to disk. Round-trips cleanly.

Performance

Features

• Single portable file — copy anywhere, query immediately
• 5 independent B-trees: entities, tasks, flows, schemas, blobs
• Blake3 content hashing for drift detection
• Freelist for space reclamation on delete
• Page cache for repeated reads
• Portable page-based database format

Store Intelligence

bit-lang-store includes built-in intelligence features that work without external dependencies or models. Every feature ships in the base package.

Zero-Dependency (ships with base package)

Feature-Flagged (optional)

# Base: all zero-dep features included
cargo add bit-lang-store

# With ML classification + anomaly detection
cargo add bit-lang-store --features ml

# With semantic embeddings
cargo add bit-lang-store --features embeddings

# Everything
cargo add bit-lang-store --features full

Contributing

git clone https://github.com/zaius-labs/dotbit
cd dotbit
cargo test --workspace

See CONTRIBUTING.md for guidelines.

License

MIT — see LICENSE.

Links

• GitHub
• crates.io
• npm
• PyPI
• Language Spec