Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
docs(hcc): clarify metric semantics and validation scope
Alfredo Lopeza6dc94916672
diff --git a/host-context-controller/CREATE_OBSERVABILITY.md b/host-context-controller/CREATE_OBSERVABILITY.mdindex f1456e1bb..2e6cf5599 100644--- a/host-context-controller/CREATE_OBSERVABILITY.md+++ b/host-context-controller/CREATE_OBSERVABILITY.md@@ -1,6 +1,6 @@# HCC create and existence-read metrics-This instrumentation supports issue #598. It observes the existing reconciliation+This instrumentation supports [issue #598](https://github.com/evenfire-ai/evenfire/issues/598). It observes the existing reconciliationpaths; it does not introduce read-before-create, extra Kubernetes requests,ownership rules, retries, or updates to resources currently left unchanged.@@ -25,6 +25,23 @@ The bounded series are initialized at zero. Re-importing metrics must preservethe registry and existing values. A zero series alone is not proof that a pathexecuted. Do not sum create outcomes to calculate request count.+`issued - conflict` is **not successful creates**: it includes other failures+(403, 5xx, network errors) and operations that have not settled. Starts and+responses can also fall in different observation windows. A successful-create+count needs matching audit success events and resource/business evidence; this+counter does not supply it by subtraction.++Select the outcome explicitly in queries. For a single scoped environment:++```promql+sum by (kind) (increase(clerum_hcc_creates_total{outcome="issued"}[5m]))+sum by (kind) (increase(clerum_hcc_creates_total{outcome="conflict"}[5m]))+```++Add the actual environment/target filters from the monitoring configuration+before comparing a deployment. These queries report attempts and conflicts,+not successful creations or a count of all completed operations.+`observeCreate` and `observeExistenceRead` invoke their callbacks once and preservethe returned value or rejected value. They do not swallow a 404, turn it into`null`, retry a failed request, or convert an error into a create. Existing caller@@ -62,14 +79,21 @@ or its read path changes; do not instrument both the API call and its retry wrap## Historical evidence and attribution limits-The original five five-minute windows contained 1,684 / 1,833 / 1,669 / 1,171 /-2,107 HCC create conflicts. These are historical observations, not acceptance+The historical aggregate `regimen-2026-09-09-agregado.csv` and its companion+BRIEF contain five-minute observations for `base1`, `base2`, `reg1`, `reg2`, and+`reg3`: respectively 1,684 / 1,833 / 1,669 / 1,171 / 2,107 HCC create conflicts.+The [measurement table in issue #598](https://github.com/evenfire-ai/evenfire/issues/598)+is the accessible published reference: its hourly rates are these observed+counts multiplied by 12. These are historical observations, not acceptancethresholds, a performance benchmark, or validation of this candidate.-A metadata-only re-query of the historical `reg3` window (2026-09-09-08:30:00–08:35:00 UTC) returned 1,846 conflicts for the four selected kinds,-below its 20,000-result cap: NetworkPolicy 1,020; Service 389; Deployment 381;-PVC 56. These exactly match the archived aggregate for those kinds.+`reg3` is the third post-deployment observation window, 2026-09-09+08:30:00–08:35:00 UTC. A separate metadata-only re-query of that window returned+1,846 conflicts for the four selected kinds, below its 20,000-result cap:+NetworkPolicy 1,020; Service 389; Deployment 381; PVC 56. These exactly match+the archived aggregate for those kinds. The remaining 261 conflicts in the+all-kind total of 2,107 are ConfigMap 189 + ServiceAccount 22 + Role 22 ++RoleBinding 22 + PodDisruptionBudget 6; the selected-kind query did not include them.| Kind | Observed name-family counts || ------------- | --------------------------------------------------------------------------------------------------------------------- |diff --git a/host-context-controller/package-lock.json b/host-context-controller/package-lock.jsonindex 123d6ff74..7d1d15364 100644--- a/host-context-controller/package-lock.json+++ b/host-context-controller/package-lock.json@@ -1,12 +1,12 @@{"name": "clerum-host-context-controller",- "version": "0.1.300",+ "version": "0.1.301","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-host-context-controller",- "version": "0.1.300",+ "version": "0.1.301","license": "SEE LICENSE IN LICENSE","dependencies": {"@clerum/codex-catalog-projection": "file:../packages/codex-catalog-projection",diff --git a/host-context-controller/package.json b/host-context-controller/package.jsonindex e1d1a70ed..808f1a816 100644--- a/host-context-controller/package.json+++ b/host-context-controller/package.json@@ -1,6 +1,6 @@{"name": "clerum-host-context-controller",- "version": "0.1.300",+ "version": "0.1.301","description": "Host Context Controller - provides McpServer CRDs to mcp-host via REST API","main": "dist/main.js","engines": {diff --git a/host-context-controller/src/createMetrics.test.ts b/host-context-controller/src/createMetrics.test.tsindex 7630d9a2b..f72c72086 100644--- a/host-context-controller/src/createMetrics.test.ts+++ b/host-context-controller/src/createMetrics.test.ts@@ -140,7 +140,7 @@ describe('Kubernetes create instrumentation', () => {})- it('observes the existing POST-first conflict path without counting replace conflicts', async () => {+ it('observes the POST-first conflict path without replacing an unchanged policy', async () => {const policy: k8s.V1NetworkPolicy = {kind: 'NetworkPolicy',metadata: { name: 'metrics-policy' },diff --git a/host-context-controller/src/existenceReadMetrics.test.ts b/host-context-controller/src/existenceReadMetrics.test.tsindex 5cc84e092..afa809687 100644--- a/host-context-controller/src/existenceReadMetrics.test.ts+++ b/host-context-controller/src/existenceReadMetrics.test.ts@@ -25,6 +25,7 @@ it('initializes the real read registry before any test seeding', async () => {expect(Object.keys(sample.labels).sort()).toEqual(['kind', 'outcome'])})+// Pins the documented wrapped inventory; does not discover new unwrapped reads.it('observes the documented physical GET expressions without wrapping snapshots or lists', () => {const inventory: Record<string, number> = {'utils.ts': 1,diff --git a/host-context-controller/src/metrics.ts b/host-context-controller/src/metrics.tsindex 151c8f226..6579e377f 100644--- a/host-context-controller/src/metrics.ts+++ b/host-context-controller/src/metrics.ts@@ -315,7 +315,7 @@ export const CREATE_KINDS = [export type CreateKind = (typeof CREATE_KINDS)[number]export const createsTotal = counter({name: 'clerum_hcc_creates_total',- help: 'Kubernetes create events: issued attempts, conflict responses (a subset of issued), and creates skipped after reading an existing object, by kind.',+ help: 'Kubernetes create events: issued attempts, conflict responses (a subset of issued), and skipped (reserved; zero in this instrumentation stage), by kind.',labelNames: ['kind', 'outcome'] as const,})for (const kind of CREATE_KINDS) {