# knut-bifrost — crate card

## Reverse-engineered (from source — verify, don't trust the name)
- **One-line pitch:** Bifröst — the bridge from lakehouse tables to a graph: watch Iceberg tables (via Spark Connect or skade) and continuously materialise them as a FalkorDB property graph through a declarative-or-custom transform fabric.
- **Does:** A `Listener` runs sync rounds pulling from a `source` (`FileSource`, feature-gated `SparkConnectSource`/`IcebergSource`), applying a `MappingSpec` (`TableMapping`, `PipelineStep`, `SyncMode`) and a `TransformRegistry` of `Transform`s that emit `GraphMutation`s (`VertexSet`/`VertexDelete`/`EdgeSet`), which a sink (`FalkorDbSink`) applies; `SyncState`/`TableState` track incremental progress. CDC support (change rows, deletes, delta scan). Rich optional surfaces: WASM transforms (`wasmi`), Flight transforms, Airflow AIP-82 asset events, Prometheus metrics (`--metrics-file` / live `/metrics` HTTP), a `bifrost` CLI, and a test-matrix status emitter.
- **Key deps:** `graphar` + `graphar-falkordb` (graph write), `arrow`, `redis`, `tokio`, `async-trait`, `tracing`, `serde_yaml`; feature-gated `spark-connect`(+arrow-56 IPC bridge), `skade` (Iceberg), `wasmi`+`arrow-ipc`, `arrow-flight`+`tonic`, `reqwest` (Airflow), `clap`+`tracing-subscriber` (CLI), `tiny_http` (metrics), `nornir-testmatrix`.
- **Shape:** lib + `bifrost` bin (feature `cli`); large, most feature-gated. Modules: `listener`, `source`, `sink`, `mapping`, `mutation`, `transform`, `registry`, `state`, `metrics`(+`_http`), `airflow`, `wasm`, `flight`, `testmatrix`. Companion `wasm-guest/` sub-crate (excluded from workspace).
- **Observed role in the workspace:** The flagship ingest/materialisation engine. Consumes graphar + graphar-falkordb; benched by `xtask`; its `airflow` module is a designed downstream of `knut-pipelines` run events.

## Fill in (one line each — only the human knows these)
- Primary consumer(s): 
- Why it exists (vs the obvious alternative): 
- Hard constraint (airgap / no-C-deps / no-FFI / pure-Rust / etc.): 
- Release cadence & independence (rides a parent? own repo someday?): 
- Status (production / prototype / experimental / stubbed): 
- Must-NOT-change invariant: 
- Biggest known gap or TODO: 
- Anything a newcomer would get wrong about it: 
