graphd

graphd is a local-first graph execution, provenance, cache, and inspection toolkit for engineering flows that cross tool and domain boundaries.

It is useful as a standalone utility belt and as a full graph framework:

• use graphd mtime, graphd cache, graphd sources, or graphd ops without adopting the full framework
• author frozen graph plans in Rust or Python
• declare task inputs, outputs, tools, runtime data, and external artifacts
• validate observed behavior against declared intent
• reuse or restore cached outputs with typed reason codes
• inspect, explain, diff, visualize, and export recorded runs

The broader methodology is described in docs/tutorials/graphd-methodology-for-cross-domain-engineering.md.

Quickstart From A Checkout

Build and run the CLI:

cargo run -p graphd -- --help

Run the core Rust tests:

cargo test --workspace

Run the Python API tests:

python -m unittest python.tests.test_api

Run the Svelte browser app checks:

cd apps/graphd-web
npm test
npm run check

Generate full local coverage reports:

scripts/coverage.sh

Run the v1 smoke path:

scripts/v1-smoke.sh

Run the full test suite:

scripts/tests.sh

Run the full build, test, and example matrix:

scripts/all.sh

That smoke script runs the canonical hierarchical example, records provenance, and exports inspection, visualization, lifecycle, trace, metrics, and supply-chain artifacts under target/graphd-v1-smoke/.

Where To Start

Standalone utility users:

• docs/tutorials/hardware-smoke-flow.md
• docs/tutorials/cache-aware-preview.md
• docs/tutorials/authoring-source-elaboration.md

Python authors:

• docs/tutorials/python-native-bindings.md
• python/examples/basic_pipeline.py
• python/examples/hierarchical_pipeline.py

TypeScript authors:

• docs/tutorials/typescript-node-authoring.md
• packages/graphd/examples/basic_pipeline.ts
• packages/graphd/examples/hierarchical_pipeline.ts

Rust authors:

• docs/authoring-surface.md
• crates/graphd-core/examples/rust_pipeline.rs
• crates/graphd-core/examples/hierarchical_flow.rs

Framework-embracing users:

• docs/tutorials/graph-dry-run.md
• docs/tutorials/run-inspection.md
• docs/tutorials/live-visualization-service.md
• docs/tutorials/visualization-snapshot-and-events.md
• docs/tutorials/graphd-methodology-for-cross-domain-engineering.md
• docs/tutorials/cross-domain-reference-flows.md

Release-readiness and supported-surface notes live in docs/release-readiness.md.