Skip to content

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.md
index 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 reconciliation
paths; 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 preserve
the registry and existing values. A zero series alone is not proof that a path
executed. 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 preserve
the 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 acceptance
thresholds, 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.json
index 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.json
index 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.ts
index 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.ts
index 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.ts
index 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) {