Metadata-Version: 2.5
Name: vesma-vitals
Version: 0.1.2
Summary: Honest measurement methodology and instrumentation for the vesma memory server: health contour for every function, value proof for promised functions
Requires-Python: >=3.12
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <strong>🇬🇧 English</strong> · <a href="https://github.com/vesmaro/vesma-vitals/blob/main/README.ru.md"><strong>🇷🇺 Русский</strong></a>
</p>

# vesma-vitals

**Methodology and instrumentation for honest measurement of the [Vesma](https://github.com/vesmaro/vesma) memory server.**
Prove — or honestly refute — every promise: dynamic context, the right memory
per request, token savings, the health of every subsystem.

[Navigation](#navigation) · [What it is](#what-it-is) · [Why a separate project](#why-a-separate-project) · [Architecture](#architecture) · [Documentation](#documentation) · [Status](#status)

## What it is

The Vesma owner framed the problem (2026-09-09): "in words and in docs everything
looks great, but in practice there is no feeling that the context is REALLY composed
dynamically. How many tokens do we actually save? Does the right instruction or a
piece of memory get substituted on request?"
The server stands (S1–S4) measure output quality and latency — none answers
**what memory gives the loop** or **whether every function actually works**.

vesma-vitals closes this gap with two circuits:

| Circuit | Question | Scope |
|---|---|---|
| **Health** | "Does the function work?" | Every server function: invoked / succeeded / latency / errors. Rule: no function ships in a release without its own circuit. |
| **Value** | "What does the function contribute?" | Only functions with a product promise. Causal value ("how many tokens saved") is proved only by the two-arm S5 replay stand — "saved X" claims from passive data are banned. |

Both decisions were made by the Vesma Architectural Committee (2026-09-09,
mnemos record `7ec9dda3` core + `061398fe` addendum "full functionality");
ADR-0026 is the formal record. This repository is the implementation.

## Why a separate project

- **Trust boundary**: the metrics collector is a guest in the server. Code isolation
  rules out accidental coupling of telemetry with the `assemble_context` pipeline
  and the main store.
- **Embedding contract**: vesma-vitals embeds into vesma at a minimal set of points
  (10 defined boundaries); the server does not depend on it.
- **Speed**: its own CI, its own releases, its own review cycle — metrics do not
  wait for the server's release window.
- **Reusability**: the methodology applies to any memory server with the same
  contract shape (harness → memory → model).

## Navigation

| Section | Contents | Audience |
|---|---|---|
| [docs/methodology.md](docs/methodology.md) | Full methodology: zones, circuits, metrics, statuses, phases | Everyone — entry point |
| [docs/token-economy.md](docs/token-economy.md) | Token economy — metric #1: schema rent, tokens-per-task, savings vs baseline, break-even N* | Anyone comparing models/tools/methods |
| [docs/architecture.md](docs/architecture.md) | Components, data schema, collection points, Prometheus hybrid | Implementers |
| [docs/decisions/](docs/decisions/) | Decision log (ArchCom canon carried over) | Future contributors |
| [docs/claims.md](docs/claims.md) | Claims ledger: promise → metric → status | Owner — "what is already proven" |
| [docs/experiments/](docs/experiments/) | Pre-registrations (anti-HARKing, before the first run); template — [TEMPLATE.md](docs/experiments/TEMPLATE.md) with a mandatory "Token savings" section before the verdict | Analysts |
| [src/vesma_vitals/](src/vesma_vitals/) | Code: sink, ledger, exposer, S5 stand | Implementers |
| [CHANGELOG.md](CHANGELOG.md) | Change history | Everyone |

## Architecture

```mermaid
flowchart LR
    subgraph VESMA["Vesma server (unchanged)"]
        AC[assemble_context and others]
        EP[10 boundaries: MCP / REST / background / CLI]
    end
    subgraph VITALS["vesma-vitals"]
        SINK["MetricsSink<br/>allowlist, fail-closed"]
        LEDGER[("metrics.sqlite sidecar<br/>5 born-final tables")]
        S5["S5 memory-value stand<br/>two arms on/off"]
        EXP["Prometheus hybrid<br/>counters + p50/p95 from rollup"]
        REPORT["Report: F8/F9 traffic light<br/>PASS / FAIL / NO-DATA"]
    end
    EP -->|verb, status, latency, project| SINK
    SINK --> LEDGER
    LEDGER --> EXP
    LEDGER --> S5
    S5 --> REPORT
    EXP --> REPORT
```

Key properties: allowlist schema **with no columns for raw text** (privacy by
structure, not by filtering), keyed-HMAC fingerprints, born no-federate, TTL
30/90 days fail-loud, status taxonomy — invariant / corridor / verdict.

## Documentation

| Document | Role |
|---|---|
| [docs/methodology.md](docs/methodology.md) | Methodology canon: what and how we measure, thresholds, honesty |
| [docs/architecture.md](docs/architecture.md) | Technical specification of the implementation |
| [docs/decisions/0001-two-circuits.md](docs/decisions/0001-two-circuits.md) | Why two circuits, not "value for everything" |
| [docs/decisions/0002-sidecar-ledger.md](docs/decisions/0002-sidecar-ledger.md) | Why a sidecar store, not tables in the main store |
| [docs/decisions/0003-family-boundaries.md](docs/decisions/0003-family-boundaries.md) | Metric-family boundary rule (theme, not tier) |

## Status

**Foundation laid (2026-09-09); phase A in progress.** The passive-collection
library core is ready (born-final schema + C1 canary + `MetricsStore`); vesma
integration is a separate PR in the server repo. Full status —
[docs/status.md](docs/status.md). Promises and their measured status —
[docs/claims.md](docs/claims.md).

## Critical actions

| Action | Command | Safety |
|---|---|---|
| Reset metrics.sqlite (local metrics store) | `rm <data_dir>/metrics.sqlite` | Allowed: metrics are not audit records; the store is recreated born-final |
| Full re-install of the vitals surface | `rm -rf <data_dir>/vitals` | Allowed: does not touch the main vesma store |
| Disable collection | `vitals.enabled: false` in config | Allowed: non-fatal write refusal by design |

Any action touching the main vesma store is performed only by vesma's own means —
vesma-vitals has no write API into it.

---

Licensing is the owner's decision; the project inherits the canon of the Vesma
ecosystem ([vesma](https://github.com/vesmaro/vesma) — the server,
[vesma-eyes](https://github.com/vesmaro/vesma-eyes) — the web viewer).