npm package: @ontologyio/schedule-bit
Description: Self-validating hierarchical scheduling system using fractal binary encoding
Latest version: 1.0.0

# Fractal Binary Schedule

A dimension-agnostic hierarchical bitmask library for scheduling and spatial allocation with O(1) queries, pluggable hashers, and Merkle tree support.

## Features

✅ **Generic Framework**: Define any hierarchical dimension (temporal, spatial, spectral)
✅ **Zero Collisions**: SHA-256 hasher (default) guarantees zero collision risk
✅ **Merkle Trees**: Hierarchical pattern identity for efficient O(1) schedule comparison
✅ **O(1) Queries**: Instant slot lookups via hash-based addressing
✅ **Sparse Storage**: Only occupied addresses stored (~50% reduction)
✅ **Parametric Addressing**: Query any value (year 2025, BCE, far future) without entity creation
✅ **Pattern Algebra**: AND/OR/XOR operations for schedule layering and conflict detection
✅ **Pluggable Backends**: In-memory, OPFS, or custom storage adapters
✅ **Preset Configs**: Temporal, spatial grid, and high-resolution time out of the box
✅ **BitVision**: Modular binary visualization system with multiple themes and export formats

## Quick Start

### Fractal Schedule (Generic System)

```typescript
import { FractalSchedule } from 'schedule-bit/fractal';
import { TEMPORAL_SCHEDULE_CONFIG } from 'schedule-bit/presets';

// Create temporal schedule (SHA-256 hasher, Merkle tree support)
const schedule = new FractalSchedule(TEMPORAL_SCHEDULE_CONFIG);

// Occupy/query slots
schedule.occupySlot({ year: 2025, month: 5, day: 15, hour: 14 });
schedule.isSlotOccupied({ year: 2025, month: 5, day: 15, hour: 14 }); // true

// Merkle tree comparison (O(1) instead of O(365 days))
scheduleA.getYearHash(2025) === scheduleB.getYearHash(2025); // instant
```
## Installation

```bash
bun install
```

## Development

```bash
bun test              # Run all tests
bun run typecheck     # Type checking
bun run lint          # Linting
bun run check         # All checks (typecheck + lint)
bun run cli           # Interactive CLI demo
bun run example       # Run examples
```

**This project uses Bun** (not Node.js/npm). See [Contributor Setup](./docs/tutorials/contributor-setup.md) for full dev environment guide.

## Documentation

This project uses the [DEP (Documentation Engineering Protocol)](https://github.com/maxios/DEP) for structured documentation. The `.docspec` file defines audiences, governance, and doc architecture.

**Start here:** [Documentation Index](./docs/index.md)

### By Audience

**Library Consumer** — integrate schedule-bit into your application:
1. [Getting Started](./docs/tutorials/getting-started.md) — install, create a schedule, occupy and query slots
2. [Choose a Hasher](./docs/how-to/choose-a-hasher.md) — SHA-256 vs FNV1a selection guide
3. [Create a Custom Dimension](./docs/how-to/create-custom-dimension.md) — define your own hierarchy
4. [API Reference](./docs/reference/api.md) — complete API documentation
5. [Preset Configurations](./docs/reference/preset-configs.md) — temporal, spatial, and high-res time

**Contributor / Extender** — extend the library with new configs, hashers, or backends:
1. [Contributor Setup](./docs/tutorials/contributor-setup.md) — dev environment, testing, conventions
2. [Implement a Storage Backend](./docs/how-to/implement-storage-backend.md) — custom storage adapters
3. [Architecture](./docs/explanation/architecture.md) — system design and key decisions
4. [Fractal Architecture](./docs/explanation/fractal-architecture.md) — the generic dimension-agnostic system

**AI Agent** — see [CLAUDE.md](./CLAUDE.md) for codebase conventions and quick reference.

### By Type

| Section | Description |
|---------|-------------|
| [Tutorials](./docs/tutorials/) | Getting started, contributor setup, fractal quick start |
| [How-To Guides](./docs/how-to/) | Choose a hasher, custom dimensions, storage backends, visualization |
| [Reference](./docs/reference/) | API, CLI, benchmarks, presets, dimension config schema |
| [Explanation](./docs/explanation/) | Architecture, Merkle trees, bitmap operations, reverse queries |
| [Decision Records](./docs/decision-records/) | Architectural decisions and rationale |

## Architecture

```
FractalSchedule<Config>
  ├─→ DimensionConfig (defines hierarchy: parametric → levels → leaf slots)
  ├─→ IHasher (pluggable: SHA-256 Merkle or FNV1a)
  └─→ IFractalStorage (stores AddressKey → PatternKey)
```

- **Parametric Level**: Unbounded top-level (e.g., year, region_id)
- **Cyclical Levels**: Bounded nested levels (e.g., month, day) — stored sparsely
- **Leaf Slots**: Discrete bitmask (e.g., 24 hours) — encoded as bigint
- **Storage**: 7 bytes per occupied address (zero collision risk with direct pattern storage)

See [Architecture Deep-Dive](./docs/explanation/architecture.md) and [Merkle Tree Hashing](./docs/explanation/merkle-tree-hashing.md) for details.

## Performance

Benchmarked with 48,620 pizza sales orders ([full benchmark](./docs/reference/benchmarks.md)):

| Operation | Throughput | Latency |
|-----------|------------|---------|
| `isSlotOccupied` | 7.9M ops/s | 0.1 μs |
| `hasConflict` (2 schedules) | 5.2M ops/s | 0.2 μs |
| `findGroupMeetingSlot` (4 schedules) | 381K ops/s | 2.6 μs |
| Pattern algebra (AND/OR/XOR) | 5-6M ops/s | — |

## Technology

Built with:
- [Bun](https://bun.sh) — Fast JavaScript runtime
- TypeScript — Type safety
- BigInt — Bitmask encoding
- SHA-256 / FNV-1a — Pluggable hash functions

## License

MIT