Outcrop

A DBMS whose storage layer is a folder of markdown files.

Record = one .md file with YAML frontmatter. Table = folder. Git is the transaction and safety layer — every transaction is a readable diff. The DBMS surface (SQL + graph + full-text via DataFusion and tantivy, gRPC + MCP) is the primary interaction mode; markdown is the durable, human-readable, git-diffable substrate. The conceptual architecture (with per-component role tooltips) lives at docs/architecture.html, served as the Architecture page of the docs site. Bundles in and out conform to the Open Knowledge Format (OKF) v0.2 (vendored with provenance at docs/okf/, kept current by the OKF spec watch workflow). External writers (Obsidian, git pull, agents, Finder) are first-class citizens.

• docs/ETHOS.md — why it's built this way: the principles, each wired to the mechanism that enforces it (also queryable as records in bundle/ethos/).
• BRIEF.md — the design brief: architecture and the non-negotiable decisions.
• DEMO.md — the full loop in exact commands (seed → query → external edit → scenario → merge conflict → resolve → MCP → canvas).
• RUNLOG.md — build-run decisions, deviations, open questions.
• docs/CANVAS.md — canvas roadmap: aggregate cards, wired data flows, agent/skill embedding, themes, media cards.
• editors/README.md — IDE support: outcrop lsp speaks the Language Server Protocol; setup for VS Code, Neovim, JetBrains, Zed, and Helix.

Layout

Path	What
crates/outcrop-store	Lossless document model (byte-span edits), atomic writes, watcher, link-graph index
crates/outcrop-schema	Per-folder _schema.yaml validation; policies ignore\|warn\|block
crates/outcrop-txn	Git-backed transactions, scenarios, field-level merge, history/restore/snapshots
crates/outcrop-query	DataFusion SQL over folders; search(), neighbors(), links_to(), paths()
crates/outcrop-server	gRPC (frozen contract in proto/outcrop.proto) + MCP stdio server
crates/outcrop-cli	outcrop binary: the whole surface for scripting and CI
clients/	SwiftUI macOS canvas; Android/Windows generated-client stubs
fixtures/corpus	Deterministic OKF v0.2 sample bundle (200 records, planted violations)

Quick start

cargo build -p outcrop-cli
cp -r fixtures/corpus /tmp/bundle
target/debug/outcrop --root /tmp/bundle init
target/debug/outcrop --root /tmp/bundle query "SELECT name, status FROM projects LIMIT 5"

Then follow DEMO.md.

Guarantees (and honest limits)

• An UPDATE touching one frontmatter field leaves every other byte of the file identical (property-tested).
• A file that violates folder constraints is a valid file and a flagged record — never corruption. block policy applies to writes through Outcrop.
• Reads are snapshot reads against the last committed state; we do not pretend to serializable isolation over a filesystem shared with humans.
• Crash recovery is git status in a trench coat: pending changes are listed, then adopted or discarded — byte-identically.

Development

cargo test --workspace
cargo fmt --all --check && cargo clippy --workspace --all-targets -- -D warnings

CI enforces fmt, clippy -D warnings, tests, and an 80% line-coverage gate on the core crates.

Docs & the self-describing bundle

Every build uploads two artifacts: outcrop-okf-bundle (the bundle/ OKF bundle describing Outcrop itself, dogfood-verified with outcrop validate) and outcrop-docs-site (the MkDocs site built by scripts/build-site.sh). The site deploys to GitHub Pages from the default branch — enable it once under Settings → Pages → Source: GitHub Actions.