khive-runtime 0.19.0

Composable Service API: entity/note CRUD, graph traversal, hybrid search, curation.
Documentation
# Runtime benchmarks

`runtime_reads` and `runtime_writes` measure the composable runtime API with
Criterion 0.5.1.

These are service-level, in-memory SQLite workloads, not daemon, network, disk
durability, model inference, or pack-dispatch measurements. Each target uses one
current-thread Tokio executor; SQLite's own blocking work retains its normal
execution path. Both targets use ten samples, a 100 ms warmup and a one-second
measurement target unless Criterion command-line options override them. Setup can
make total wall time substantially longer than the measured interval.

## Run commands

A qualified-host baseline runs every scenario with its target's own Criterion
configuration. Run from `crates/`:

```sh
cargo bench -p khive-runtime --benches -- --noplot
```

For a quick trend observation, run from the same directory:

```sh
cargo bench -p khive-runtime --benches -- --quick --noplot
```

Quick mode skips the warmup, ignores the configured sample count and keeps only
two timings. It doubles the iteration count until its variation target is met
after at least 100 ms, or the measurement time runs out. A first iteration that
exceeds that time yields two nearly identical values from that one timing.
Quick-mode results are trend observations only and never enter a qualified
baseline.

## Scenarios

Names below are Criterion group/scenario names. All baseline cells are pending;
there are no measured values in this initial ledger.

| Group                         | Scenarios                      | Measured operation                                                  | Input                                                                                     | Baseline |
| ----------------------------- | ------------------------------ | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -------- |
| `runtime_search_notes`        | `terms_{1,3,5}/{10,20,50}`     | `search_notes`, including result materialization                    | 10K notes and FTS documents; lexical search with embeddings disabled                      | pending  |
| `runtime_hybrid_entities`     | `{10,50}`                      | `hybrid_search`, including fusion and entity materialization        | 10K entities and FTS documents, 10K seeded 384-dimensional vectors; supplied query vector | pending  |
| `runtime_neighbors`           | `10k_edges_one_hop`            | `neighbors`, outgoing single-hop lookup and enrichment              | 10K edges, root with four children                                                        | pending  |
| `runtime_bfs`                 | `{1,2,3,4}`                    | `bfs_traverse`, including path materialization                      | 10K nodes and edges; four-way tree, leaf-to-root closing edge                             | pending  |
| `runtime_entity_stats`        | `10k`                          | `entity_stats_counts`                                               | 10K live concept entities                                                                 | pending  |
| `runtime_export_kg`           | `10k_entities_10k_edges`       | `export_kg`, archive construction without JSON serialization        | 10K entities and 10K edges; entities/sec                                                  | pending  |
| `runtime_embed_batch_stub`    | `{1,10,100}`                   | `embed_batch`, warm provider lookup and synthetic vector allocation | Short texts, constant normalized 384-dimensional output                                   | pending  |
| `runtime_create_note`         | `10k_notes_one_stub_embedding` | `create_note`, including FTS and one stub embedding/vector write    | Fresh 10K-note corpus per iteration, one new note                                         | pending  |
| `runtime_entity_attachments`  | `{100,500}`                    | Sequential `create_entity_with_attachments` calls                   | Fresh runtime; one prepublished 1 KiB content blob shared by the batch                    | pending  |
| `runtime_atomic_unit`         | `{1,3,5}`                      | `run_atomic_unit` for prepared entity-create plans                  | Fresh runtime; prepare excluded, row/FTS writes and commit included                       | pending  |
| `runtime_keyed_memory_create` | `{100,500}`                    | Sequential `create_keyed_memory` calls                              | Fresh runtime, distinct keys, no embedding provider                                       | pending  |
| `runtime_import_kg`           | `10k_entities_10k_edges`       | `import_kg`, including validation, writes and FTS reindexing        | Fresh destination, generated archive, no embedding model; entities/sec                    | pending  |

### Fixture and timing contract

Fixture generation uses seed 5643, stable UUIDs and a fixed timestamp. All data is
generated by the benchmark; no downloaded model, ignored corpus or external
database is required. The stub replaces the configured provider before its first
use, so no model is loaded. It measures runtime overhead plus vector allocation,
not inference speed or embedding quality. Search uses deterministic, nonempty
matching text. Entity hybrid vectors are seeded, varied and normalized.

Every note-search query matches every note: all notes contain the same query
terms. The `terms_{1,3,5}` axis varies query length, not match count. The
`runtime_embed_batch_stub` timings include fixed per-call work: an environment
read for the deadline, admission/timeout bookkeeping, model-alias parsing and
usage counting, in addition to warm provider lookup and vector allocation.

Read fixtures are built once per group and each scenario is exercised before its
timing loop. Those checks reject empty searches, wrong cardinalities and missing
graph/archive content. The BFS sizes at depths 1–4 are 5, 21, 85 and 341 nodes,
including the root; the full graph still contains 10K nodes and edges.

The import fixture has no embedding model, so its reindexing is FTS only. The
import archive uses `concept -[extends]-> concept`, which the runtime's
endpoint contract accepts. The read/export fixture retains its original
`depends_on` relation. Storage seeding alone does not validate endpoint kinds;
`import_kg` does, so an invalid relation would measure skipped edges. Each import
iteration verifies an empty destination before timing, retains the full 10K
entity/10K edge summary assertions, rejects every skipped edge, and reads back
all records afterward. The untimed readback compares every archived entity and
edge field by stable ID, including edge endpoints, relation, weight, metadata
and timestamps. Export timestamps are intentionally fresh; storage-only fields
not represented by the archive are outside that comparison.

Writes use sequential `iter_custom` loops: one fresh fixture per iteration, an
`Instant` interval around the requested operation, and untimed teardown. Only one
write fixture is live at once. This prevents later iterations from measuring
overwrites, keyed replays or an ever-growing database. Fixture generation, model
warmup, blob publication and atomic preparation are excluded. Batch write times
include per-call argument cloning and returned-value disposal; single-note,
atomic and import result checks/disposal follow their timers. Read loops include
result disposal. Executor entry is included throughout.

The note-create corpus starts with 10K notes and FTS documents, without vectors
for those existing notes. The timed new note receives one embedding. The entity
attachment row measures metadata attachment to an existing blob, not upload or
hashing of 100/500 independent blobs. Its fixture also has no embedding model;
entity indexing is FTS only. Atomic timing excludes deferred
post-commit effects; its runtime has no embedding provider.

### Search and traversal workloads

`hybrid_search` returns entities (`src/retrieval.rs`); its group uses 10K entities
and vectors. The separate note-search group covers 10K notes. `neighbors`
(`src/operations/traversal.rs`) measures one outgoing hop from a root with four
children. BFS measures traversal at depths 1–4 in its own group.

## Performance guarantees

These rows define advisory measurement goals, not numerical promises or enforced
latency thresholds. All current baselines, including machine, toolchain and
measured commit, are pending.

| Operation       | Input                                                | Metric         | Bound                                        | Baseline |
| --------------- | ---------------------------------------------------- | -------------- | -------------------------------------------- | -------- |
| create_note     | single note + 1 embedding                            | latency median | Advisory trend against the recorded baseline | pending  |
| search_notes    | 10K notes, 3 terms, top_k=20                         | latency median | Advisory trend against the recorded baseline | pending  |
| hybrid_search   | 10K entities + 10K vectors, top_k=10                 | latency median | Advisory trend against the recorded baseline | pending  |
| neighbors       | 10K edges, one outgoing hop, root with four children | latency median | Advisory trend against the recorded baseline | pending  |
| run_atomic_unit | 5-op atomic                                          | latency median | Advisory trend against the recorded baseline | pending  |
| export_kg       | 10K entities + 10K edges                             | throughput     | Advisory trend against the recorded baseline | pending  |

Criterion's headline time estimate is not automatically a median. Record the
median estimate from each scenario's `new/estimates.json` for latency rows, and
derive export/import entities/sec from the recorded time estimate with its
statistic named. Keep the full Criterion output so dispersion is available.

A recorded baseline must identify the full commit, Rust toolchain, OS, CPU,
memory, command, Cargo features, Criterion options, runtime/storage configuration
and fixture seed. The benchmark's self dev-dependency enables `khive-runtime`'s
`fault-injection` and `test-internals` features; dev-dependencies also enable
`khive-db/test-support`, `khive-storage/test-support` and Tokio's `test-util`.
This differs from the shipped binaries' normal dependency on `khive-runtime`,
which enables none of that crate's optional features. Record these benchmark
features alongside any additional command-line feature selections.

Keep a fixed reference alongside later observations. Compare like
scenarios and report uncertainty; no fixed-percentage timing regression gate is
introduced here. Every row is advisory timing or throughput, so this
suite introduces no allocation/count guarantee or associated deterministic gate.