<!-- nornir:class: design -->
# korp-collectors — version scheme
> **What it is.** How this leaf reports *which build is running* — the crate
> version plus the exact git commit it was compiled from — per the LAW that every
> daemon binary must be able to answer `--version` with a git hash.
## The stamp
The canonical build stamp is:
```
<name> v<CARGO_PKG_VERSION> (<git-hash>)
```
e.g. `korp-collectors v0.1.7 (38e6b2c7e0db7cff88e219f8b441d208f211e416)`.
- **`<name>` / `<version>`** — `CARGO_PKG_NAME` / `CARGO_PKG_VERSION` from
`Cargo.toml`. The version is plain **SemVer**; bump it on release like any crate.
- **`<git-hash>`** — the commit HEAD pointed at when the crate was built, captured
into `COLLECTORS_GIT_HASH` by `build.rs`. `unknown` when no `.git` is reachable
(e.g. a published-crate build), so the stamp never fails a build.
## How the hash is captured — pure filesystem, zero shell
`build.rs` reads the git state **off disk itself** — it never shells out to `git`
and never spawns a `Command` (the pure-Rust / zero-shell LAW). It resolves:
- a normal `.git` **directory** or a `.git` **file** (`gitdir:` pointer — worktree
/ submodule), including the worktree `commondir` split;
- a symbolic `HEAD` (`ref: refs/heads/<branch>`) via loose refs **or** `packed-refs`;
- a **detached** HEAD (raw commit sha).
It emits `cargo:rerun-if-changed` for `HEAD`, the resolved ref file, and
`packed-refs`, so the stamp refreshes when — and only when — the commit moves.
## Where it surfaces
- **`--version` / `-V`** on the `korp-collectors` binary — prints the stamp and
**exits before any daemon boot**. korp's own daemon runner shares the same
`korp_collectors::handle_version_flag(...)` + `version_string()`, so every entry
point reports one identical stamp.
- **BIOS health surface** — `daemon::BiosBus::version(collector)` posts the stamp
as an append-only provenance fact, so the startup banner / matrix record exactly
which build is online.
- **Library API** — `korp_collectors::build::{NAME, VERSION, GIT_HASH}` and
`korp_collectors::version_string()` for any consumer (korp, facett-demo).