____  ____  ___  ____    ___   ___  ____    _
  / __ \/ __ \/ _ \/ __ \  / _ \ / _ \|  _ \  / \
 / /_/ / /_/ /  __/ / / / | | | | | | | | | |/ _ \
/_____/ .___/\___/_/ /_/  | |_| | |_| | |_| / ___ \
      /_/                   \___/ \___/|____/_/   \_\

openOODA — Sovereign Systems Language for the AI Era

openooda.org

---

This repo: blackbox

Flight recorder, crash autopsy engine, and compiler AST diffing subsystem.

blackbox/
├── ANCHOR.oo        Root front door and version surface
├── record/          Telemetry schemas, flight event records, ring buffer
├── autopsy/         Autopsy parser, failure locator, root-cause classifier
├── diff/            AST pass diffing and compiler stage comparator
├── bridge/          Process execution under ProcessCap and MCP bridge
├── cli/             Command line interface (autopsy, diff, trace)
├── qa/              Crash test fixtures, double-run proofs, suite runner
└── docs/            Subsystem specification in ASD-STE100

Purpose

The blackbox CLI reads crash autopsy JSON, dumps live oodac tokens output, auto-records bounded flight capsules for failing spawned processes, heals sources from autopsy coordinates, and gates CI on token-dump drift. run --record <capsule> -- <cmd> [args] spawns a child under ProcessCap (sys_exec captures stdout+stderr, 16MiB bound) and, only on failure, persists a bounded capsule (command, exit status, truncated output, single overwrite per path) to the explicit path; successes write nothing. diff locates the compiler from OODA_COMPILER or OODAC_BIN (no PATH hunt), runs tokens, and exits nonzero when two-file token dumps drift. heal [path] [--json] parses autopsy, applies the patch guard under FsWriteCap, validates via oodac check, rolls back on failure, and prints machine-readable {"ok":...} with --json. inspect runs live tokens, check, emit-c, or build and prints the child text, including gcc diagnostics. trace prints .blackbox/flight.json when that file exists and is non-empty; otherwise it prints ERR.

CLI Usage

# Parse autopsy JSON and output 1-turn agent diagnosis
blackbox autopsy path/to/autopsy.json

# Run a child; on failure persist a bounded flight capsule (exit nonzero)
blackbox run --record flight-fail.json -- "$OODA_COMPILER" check path/to/file.oo

# Heal a source defect from autopsy coordinates (machine-readable with --json)
blackbox heal path/to/autopsy.json --json

# Run oodac tokens on a file (requires OODA_COMPILER or OODAC_BIN)
blackbox diff path/to/file.oo

# Compare two files; exits nonzero when token dumps drift (CI gate)
blackbox diff path/to/before.oo path/to/after.oo

# Run a live oodac stage (tokens, check, emit-c, or build)
blackbox inspect check path/to/file.oo
blackbox inspect emit-c path/to/file.oo
blackbox inspect build path/to/file.oo

# Print a written flight log, or ERR if none exists
blackbox trace

Governance and Constraints

• Pure file laws: source files use only .oo and specifications use .oot.
• Strict line limit: every .oo and .oot file contains 256 lines or fewer.
• Academy headers: all .oo files contain # Title, Logline, Setup, and Beats.
• Import rules: all cross-directory imports use repository-relative paths without parent escapes.

The Polyrepo Ecosystem

Repo	Purpose
openOODA/openOODA	Governance, RFCs, and constitutional invariants
openOODA/ooda	Unified developer workflow driver
openOODA/oodac	Sovereign compiler and AST engine
openOODA/oodar	Low-level C runtime substrate
openOODA/std	Standard library
openOODA/mcp	Model Context Protocol server
openOODA/opm	Cryptographic package manager
openOODA/lsp	Language Server Protocol daemon
openOODA/catalog	Official ecosystem package catalog
openOODA/website	Official openOODA website source
openOODA/install	Installation scripts and platform packages
openOODA/.github	Shared GitHub workflows and community health
openOODA/blackbox	Operational Logistics: Agent-native execution flight recorder and crash autopsy engine

License

Dual-licensed under your choice of MIT or Apache 2.0. See LICENSE for full terms.