Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
test(hcc): classify excluded reads across production sources
Alfredo Lopezbc6ccc66ea03
diff --git a/host-context-controller/CREATE_OBSERVABILITY.md b/host-context-controller/CREATE_OBSERVABILITY.mdindex 9935135a5..bf0001a29 100644--- a/host-context-controller/CREATE_OBSERVABILITY.md+++ b/host-context-controller/CREATE_OBSERVABILITY.md@@ -26,7 +26,12 @@ Create outcomes are mutually exclusive and increment only after the callbacksettles. The former `issued` series is removed. Summing `created + conflict + error`counts completed attempts; `skipped` is not an invocation and is excluded from thatsum. Operations still in flight are not counted. A create resolving to null or-undefined still counts as resolved; telemetry does not assert object persistence.+undefined still counts as resolved; telemetry does not assert object persistence. The same applies to+`found`: it reports a resolved read callback, not semantic presence, readiness,+or authorization correctness. Read `error` intentionally groups status and+transport failures for the instrumented paths; it cannot identify a 403 storm+or describe errors from excluded reads by itself. Diagnostics require separate+bounded evidence, without placing status messages or resource data in labels.The bounded series are initialized at zero: 40 create series and 30 read series.Re-importing metrics must preserve the registry and existing values. A zero series@@ -86,6 +91,16 @@ paths unrelated to a create decision are excluded. An already-available snapshotdoes not represent another API read. The inventory must be updated when a writeror its read path changes; do not instrument both the API call and its retry wrapper.+The read-inventory test scans all production TypeScript under `src` for direct+dot-property `readNamespaced*`/`readCluster*` calls. Each must be observed or match an explicit+exclusion keyed by file, enclosing operation and SDK method, with an expected+expression count and reason. It currently accounts for 21 observed expressions+and 43 excluded ones. New unclassified reads and stale exclusions fail the test.+This is structural coverage, not execution evidence: changed purpose inside an+excluded operation still needs review, and computed-property or indirect/aliased calls are outside this+static-analysis guarantee. The behavioral tests and deployed validation+remain separate; an AST pass does not prove all those paths ran.+## Historical evidence and attribution limitsThe historical aggregate `regimen-2026-09-09-agregado.csv` and its companiondiff --git a/host-context-controller/package-lock.json b/host-context-controller/package-lock.jsonindex aff8312f9..4587b15c7 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.302",+ "version": "0.1.303","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-host-context-controller",- "version": "0.1.302",+ "version": "0.1.303","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 9a482303d..e3d11c180 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.302",+ "version": "0.1.303","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/existenceReadMetrics.test.ts b/host-context-controller/src/existenceReadMetrics.test.tsindex cf9f87337..808a99748 100644--- a/host-context-controller/src/existenceReadMetrics.test.ts+++ b/host-context-controller/src/existenceReadMetrics.test.ts@@ -1,6 +1,6 @@import { beforeEach, describe, expect, it, vi } from 'vitest'import type * as k8s from '@kubernetes/client-node'-import { readFileSync } from 'node:fs'+import { readFileSync, readdirSync } from 'node:fs'import { join } from 'node:path'import ts from 'typescript'import { CREATE_KINDS, createsTotal, existenceReadsTotal, registry } from './metrics'@@ -25,9 +25,162 @@ 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> = {+// Review each exclusion when its enclosing operation changes. Counts describe+// expressions, not executions; a newly added direct read must be classified.+const readExclusions: Record<string, readonly [number, string]> = {+ 'hostReconciler.ts::readHostDeploymentOrNull::readNamespacedDeployment': [+ 1,+ 'Input to runtime binding and refresh decisions',+ ],+ 'hostReconciler.ts::refreshCodexSnapshot::readNamespacedConfigMap': [+ 1,+ 'Input allowlist snapshot',+ ],+ 'hostReconciler.ts::deleteHostRbac::readNamespacedRoleBinding': [1, 'Ownership before deletion'],+ 'hostReconciler.ts::deleteHostRbac::readNamespacedRole': [1, 'Ownership before deletion'],+ 'hostReconciler.ts::deleteHostRbac::readNamespacedServiceAccount': [+ 1,+ 'Ownership before deletion',+ ],+ 'hostReconciler.ts::deleteMcpHostRuntimeTokenSecret::readNamespacedSecret': [+ 1,+ 'Ownership before deletion',+ ],+ 'hostReconciler.ts::deleteLegacyChannelReaderRuntimeAuth::readNamespacedSecret': [+ 1,+ 'Ownership before deletion',+ ],+ 'hostReconciler.ts::validateHostSecret::readNamespacedSecret': [1, 'Input validation'],+ 'hostReconciler.ts::computeChannelReaderRevisionForHost::readNamespacedSecret': [+ 1,+ 'Input to desired revision',+ ],+ 'hostReconciler.ts::checkDeploymentReady::readNamespacedDeployment': [1, 'Readiness observation'],+ 'hostReconciler.ts::checkChannelReaderStatus::readNamespacedDeployment': [+ 1,+ 'Status observation',+ ],+ 'hostReconciler.ts::deleteRuntimeResources::readNamespacedDeployment': [+ 1,+ 'Ownership before deletion',+ ],+ 'hostReconciler.ts::deleteRuntimeResources::readNamespacedService': [+ 1,+ 'Ownership before deletion',+ ],+ 'hostReconciler.ts::deleteRuntimeResources::readNamespacedNetworkPolicy': [+ 1,+ 'Ownership before deletion',+ ],+ 'hostReconciler.ts::deleteWorkspacePvc::readNamespacedPersistentVolumeClaim': [+ 1,+ 'Ownership before deletion',+ ],+ 'hostReconciler.ts::deleteChannelReaderDeployment::readNamespacedDeployment': [+ 1,+ 'Ownership before deletion',+ ],+ 'hostReconciler.ts::deleteChannelReaderService::readNamespacedService': [+ 1,+ 'Ownership before deletion',+ ],+ 'hostReconciler.ts::deleteMcpHostCodexProxyEgressNetworkPolicy::readNamespacedNetworkPolicy': [+ 1,+ 'Ownership before deletion',+ ],+ 'hostReconciler.ts::deleteHostNetworkPolicies::readNamespacedNetworkPolicy': [+ 1,+ 'Ownership before deletion',+ ],+ 'k8sClient.ts::readSecretMetadata::readNamespacedSecret': [1, 'Authorization input metadata'],+ 'k8sClient.ts::readSecret::readNamespacedSecret': [1, 'Authorization input data'],+ 'llmHookReconciler.ts::validateSecret::readNamespacedSecret': [1, 'Input validation'],+ 'llmHookReconciler.ts::deleteServiceTargetNetworkPolicy::readNamespacedNetworkPolicy': [+ 1,+ 'Ownership before deletion',+ ],+ 'llmHookReconciler.ts::readServiceSelector::readNamespacedService': [+ 1,+ 'Input selector for another resource',+ ],+ 'llmHookReconciler.ts::deleteHostEgressNetworkPolicy::readNamespacedNetworkPolicy': [+ 1,+ 'Ownership before deletion',+ ],+ 'llmHookReconciler.ts::gcPodKey::readNamespacedDeployment': [+ 1,+ 'Ownership before garbage collection',+ ],+ 'llmHookReconciler.ts::gcPodKey::readNamespacedService': [+ 1,+ 'Ownership before garbage collection',+ ],+ 'llmHookReconciler.ts::gcPodKey::readNamespacedNetworkPolicy': [+ 1,+ 'Ownership before garbage collection',+ ],+ 'llmHookReconciler.ts::readDeploymentRollout::readNamespacedDeployment': [+ 1,+ 'Readiness observation',+ ],+ 'networkPolicyReconciler.ts::judgeLiveExactHostEgress::readNamespacedNetworkPolicy': [+ 1,+ 'Retain or revoke verdict after failure',+ ],+ 'networkPolicyReconciler.ts::replaceSafetyPolicySnapshot::readNamespacedNetworkPolicy': [+ 1,+ 'Identity check for replace-only safety path',+ ],+ 'networkPolicyReconciler.ts::deleteLegacyStaticPolicy::readNamespacedNetworkPolicy': [+ 1,+ 'Ownership before deletion',+ ],+ 'reconciler.ts::readDeploymentRollout::readNamespacedDeployment': [1, 'Readiness observation'],+ 'reconciler.ts::validateSecret::readNamespacedSecret': [1, 'Input validation'],+ 'reconciler.ts::deleteDeploymentIfHccOwned::readNamespacedDeployment': [+ 1,+ 'Ownership before deletion',+ ],+ 'reconciler.ts::deleteConfigMapIfHccOwned::readNamespacedConfigMap': [+ 1,+ 'Ownership before deletion',+ ],+ 'reconciler.ts::deleteServiceIfHccOwned::readNamespacedService': [1, 'Ownership before deletion'],+ 'sharedFileSystemReconciler.ts::assessReadiness::readNamespacedPersistentVolumeClaim': [+ 1,+ 'Readiness observation',+ ],+ 'sharedFileSystemReconciler.ts::assessReadiness::readNamespacedDeployment': [+ 1,+ 'Readiness observation',+ ],+ 'statelessLifecycleExecutor.ts::handleWakeFastPath::readNamespacedDeployment': [+ 1,+ 'Scale-only compatibility path',+ ],+ 'k8s/gfsK8sApi.ts::scaleDeployment::readNamespacedDeployment': [+ 2,+ 'Scale-only initial and retry reads',+ ],+ 'k8s/gfsK8sApi.ts::isDeploymentAvailable::readNamespacedDeployment': [1, 'Readiness observation'],+}++function readProductionSources(): Record<string, string> {+ const sources: Record<string, string> = {}+ for (const relative of readdirSync(__dirname, { recursive: true }) as string[]) {+ if (+ !relative.endsWith('.ts') ||+ relative.endsWith('.test.ts') ||+ relative.includes('__tests__')+ )+ continue+ sources[relative] = readFileSync(join(__dirname, relative), 'utf8')+ }+ return sources+}++function assertReadInventory(sources: Record<string, string>): void {+ const expectedWrapped: Record<string, number> = {'utils.ts': 1,'hostReconciler.ts': 8,'reconciler.ts': 3,@@ -36,42 +189,92 @@ it('observes the documented physical GET expressions without wrapping snapshots'k8s/gfsK8sApi.ts': 3,'networkPolicyReconciler.ts': 2,}- let total = 0- for (const [path, expected] of Object.entries(inventory)) {- const source = ts.createSourceFile(- path,- readFileSync(join(__dirname, path), 'utf8'),- ts.ScriptTarget.Latest,- true- )- let calls = 0+ const wrapped: Record<string, number> = {}+ const excluded: Record<string, number> = {}+ for (const [path, text] of Object.entries(sources)) {+ const source = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true)const visit = (node: ts.Node): void => {if (ts.isCallExpression(node) &&ts.isIdentifier(node.expression) &&node.expression.text === 'observeExistenceRead') {- calls+++ wrapped[path] = (wrapped[path] ?? 0) + 1+ expect(node.arguments).toHaveLength(2)const [kind, read] = node.argumentsexpect(ts.isStringLiteral(kind), path).toBe(true)expect(ts.isArrowFunction(read), path).toBe(true)if (ts.isStringLiteral(kind) && ts.isArrowFunction(read)) {+ expect(CREATE_KINDS).toContain(kind.text)+ expect(read.parameters).toHaveLength(0)expect(ts.isCallExpression(read.body), path).toBe(true)if (ts.isCallExpression(read.body) &&ts.isPropertyAccessExpression(read.body.expression)) {expect(read.body.expression.name.text, path).toBe(`readNamespaced${kind.text}`)- } else throw new Error(`${path}: the wrapper must observe a direct API read`)+ } else throw new Error(`${path}: wrapper must observe a direct API read`)+ }+ }+ if (+ ts.isCallExpression(node) &&+ ts.isPropertyAccessExpression(node.expression) &&+ /^read(?:Namespaced|Cluster)/.test(node.expression.name.text)+ ) {+ const parent = node.parent+ const isWrapped =+ ts.isArrowFunction(parent) &&+ ts.isCallExpression(parent.parent) &&+ ts.isIdentifier(parent.parent.expression) &&+ parent.parent.expression.text === 'observeExistenceRead'+ if (!isWrapped) {+ let owner: ts.Node | undefined = node.parent+ while (owner && !ts.isMethodDeclaration(owner) && !ts.isFunctionDeclaration(owner))+ owner = owner.parent+ const name =+ owner && (ts.isMethodDeclaration(owner) || ts.isFunctionDeclaration(owner))+ ? owner.name?.getText(source)+ : undefined+ const id = `${path}::${name ?? '<module>'}::${node.expression.name.text}`+ if (!Object.hasOwn(readExclusions, id))+ throw new Error(`Unclassified Kubernetes read: ${id}`)+ excluded[id] = (excluded[id] ?? 0) + 1}}ts.forEachChild(node, visit)}visit(source)- expect(calls, path).toBe(expected)- total += calls}- expect(total).toBe(21)+ expect(wrapped).toEqual(expectedWrapped)+ for (const [id, [count, reason]] of Object.entries(readExclusions)) {+ expect(reason.length, id).toBeGreaterThan(0)+ expect(excluded[id], `Stale or changed read exclusion: ${id}`).toBe(count)+ }+ expect(Object.values(wrapped).reduce((sum, count) => sum + count, 0)).toBe(21)+ expect(Object.values(excluded).reduce((sum, count) => sum + count, 0)).toBe(43)+}++it('classifies every direct dot-property production SDK read as observed or explicitly excluded', () => {+ assertReadInventory(readProductionSources())+})++it.each(['utils.ts', 'new-reader.ts'])('rejects an unclassified read introduced in %s', path => {+ const sources = readProductionSources()+ // Synthetic source is parsed only: no client method or network request executes.+ sources[path] =+ (sources[path] ?? '') ++ '\nfunction unclassifiedRead(client) { return client.readNamespacedService({}) }'+ expect(() => assertReadInventory(sources)).toThrow(+ `Unclassified Kubernetes read: ${path}::unclassifiedRead::readNamespacedService`+ )+})++it('rejects an exclusion after its read disappears or moves', () => {+ const sources = readProductionSources()+ delete sources['statelessLifecycleExecutor.ts']+ expect(() => assertReadInventory(sources)).toThrow(+ 'Stale or changed read exclusion: statelessLifecycleExecutor.ts::handleWakeFastPath::readNamespacedDeployment'+ )})describe('Kubernetes existence-read instrumentation', () => {