# flowRS engine

The source of the engine behind [flowRS](https://flowrs.openie.dev): what reads, checks, runs and
exports a graph without the editor, published as the continuity pledge promises
(<https://flowrs.openie.dev/docs/continuity/>).

**What this is.** A snapshot of `flowrs-core`, `flowrs-cli` (`flowrsc`) and the crates they need,
32 in all, cut from flowRS's repository at commit `f907e0756a7cb167f44d57913bce42db0d235795`. It has no git history of its own. It
builds alone: `cargo build --locked` from an empty cargo cache, then `flowrsc check`, `flowrsc run`
and `flowrsc app` on a document under `spec/conformance/` (some of those are invalid on purpose:
`spec/conformance/manifest.json` says which).

**What this is not.** The editor (IDE), the server behind flowrs.openie.dev, the hosted agent and
the firmware forge are not here. The promise about those is the pledge's fourth point.

## Build and run

```sh
cargo build --locked -p flowrs-cli
target/debug/flowrsc check spec/conformance/flowrs/add-two-numbers.flowrs
target/debug/flowrsc run spec/conformance/flowrs/add-two-numbers.flowrs --tier t0
target/debug/flowrsc app spec/conformance/flowrs/add-two-numbers.flowrs -o /tmp/my-app
```

The toolchain is pinned by `rust-toolchain.toml`. flowrs-core's tests compile generated programs
offline, so fetch once, then test:

```sh
cargo fetch --locked && (cd tools/test-crates && cargo fetch)
cargo test --locked -p flowrs-core -p flowrs-cli
```

The other crates' suites run in flowRS's own repository, and their fixtures are mostly not carried
here (see `ENGINE-CONTENTS.md`). A test that needs something this snapshot does not carry is marked
`#[ignore]`, with the reason:

- `crates/flowrs-core/tests/provenance_edit_paths.rs`, `every_write_to_the_ides_graph_says_who_wrote_it`: reads the editor's source, which is not published here
- `crates/flowrs-core/tests/platform_maths.rs`, `no_source_a_tier_runs_calls_the_platforms_maths`: reads flowrs-neuro's source, which is not in this snapshot
- `crates/flowrs-core/tests/proof_table.rs`, `the_corpus_the_canary_and_flowrsc_prove_run_kani_with_the_same_arguments`: compares flowRS's proof scripts, which are not in this snapshot
- `crates/flowrs-core/tests/proof_table.rs`, `the_table_reads_and_was_run_by_the_pinned_kani`: compares flowRS's proof scripts, which are not in this snapshot
- `crates/flowrs-core/src/graph/widgets/capture.rs`, `a_capture_from_the_file_store_decodes_as_a_chain`: reads capture files this snapshot leaves out
- `crates/flowrs-core/src/graph/widgets/capture.rs`, `the_generated_programs_agree_with_the_editor_for_every_decoder`: reads capture files this snapshot leaves out
- `crates/flowrs-core/src/graph/widgets/mod.rs`, `every_widget_is_compiled_by_a_test_or_is_a_declared_seam`: counts the two capture tests above as not compiling their widgets, and they read files left out
- `crates/flowrs-core/tests/document_spec.rs`, `every_document_in_the_repository_conforms`: counts the documents of flowRS's whole repository, most of which are not here

## Licences

Each crate carries the licence text its manifest names (Apache-2.0, or MIT OR Apache-2.0).
`spec/flowrs-document-2.md` (and version 1.0.0, `spec/flowrs-document-1.md`) is under CC BY 4.0; its schemas and corpus are under the code's licence.
What was left out of the snapshot, what was kept, and why, file kind by file kind, is
`ENGINE-CONTENTS.md`. Third-party material is named in each crate's `NOTICE`, `PROVENANCE.md` and
`LICENSES/`.

## Issues and contributions

Issues: <https://git.transaction.science/Transaction-Science/flowrs-engine/issues>. Mirror: <https://codeberg.org/Transaction-Science/flowrs-engine>.
Contributions are welcome if they benefit the project: read `CONTRIBUTING.md`.

## The crates

- `dpb-plot`
- `flowrs-app`
- `flowrs-appshell`
- `flowrs-boards`
- `flowrs-capture`
- `flowrs-cli`
- `flowrs-connect`
- `flowrs-core`
- `flowrs-decode`
- `flowrs-device`
- `flowrs-drivers`
- `flowrs-dsp`
- `flowrs-hal`
- `flowrs-iface`
- `flowrs-instruments`
- `flowrs-linux`
- `flowrs-live`
- `flowrs-math`
- `flowrs-ml`
- `flowrs-openui`
- `flowrs-record`
- `flowrs-registry`
- `flowrs-results`
- `flowrs-sandbox`
- `flowrs-schemas`
- `flowrs-sequence`
- `flowrs-sim`
- `flowrs-station`
- `flowrs-tdms`
- `flowrs-tls`
- `flowrs-transport`
- `flowrs-viz`

2009 files are carried and 4182 left out of these crates' directories; `ENGINE-CONTENTS.md` says which and why.