Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
fix(hcc): deep-stable guardrails-revision hash + order-independence test (review)
Andy Pavia55d4d375f3b2
diff --git a/host-context-controller/package-lock.json b/host-context-controller/package-lock.jsonindex c1bd6fa81..0607476da 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.172",+ "version": "0.1.173","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-host-context-controller",- "version": "0.1.172",+ "version": "0.1.173","license": "SEE LICENSE IN LICENSE","dependencies": {"@clerum/image-policy": "file:../packages/image-policy",diff --git a/host-context-controller/package.json b/host-context-controller/package.jsonindex 705941267..72a920567 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.172",+ "version": "0.1.173","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/__tests__/hostReconciler.mounts.test.ts b/host-context-controller/src/__tests__/hostReconciler.mounts.test.tsindex 3a1d353b8..5b25b9a99 100644--- a/host-context-controller/src/__tests__/hostReconciler.mounts.test.ts+++ b/host-context-controller/src/__tests__/hostReconciler.mounts.test.ts@@ -5,7 +5,6 @@ import { config as hccConfig } from '../config'import { HostReconciler, type ResolvedSfsMount } from '../hostReconciler'import { issueMcpHostRuntimeTokens } from '../mcpHostRuntimeTokenIssuerClient'import type { HostCRD } from '../types'-import { canonicalStringify } from '../utils'vi.mock('../mcpHostRuntimeTokenIssuerClient', () => ({issueMcpHostRuntimeTokens: vi.fn().mockResolvedValue({@@ -999,22 +998,19 @@ describe('HostReconciler.buildDeployment — SharedFileSystem mounts', () => {)})- it('stamps sha256(canonicalStringify(guardrails)) on the pod template when guardrails are set', () => {+ it('stamps a 64-hex guardrails-revision on the pod template when guardrails are set', () => {const reconciler = new HostReconciler(makeStubKc())const guardrails: HostCRD['spec']['guardrails'] = {hooks: { preCall: [{ id: 'h1', digest: 'sha256:abc' }] },}const host: HostCRD = { ...makeHost(), spec: { ...makeHost().spec, guardrails } }const dep = reconciler.buildDeployment(host)- const expected = createHash('sha256')- .update(canonicalStringify(guardrails as unknown as Record<string, unknown>))- .digest('hex')- expect(dep.spec!.template!.metadata!.annotations?.['clerum.io/guardrails-revision']).toBe(- expected+ expect(dep.spec!.template!.metadata!.annotations?.['clerum.io/guardrails-revision']).toMatch(+ /^[0-9a-f]{64}$/)})- it('changes the guardrails-revision on a guardrails change and is stable otherwise', () => {+ it('guardrails-revision is nested-key-order-independent and content-sensitive', () => {const reconciler = new HostReconciler(makeStubKc())const revFor = (guardrails: HostCRD['spec']['guardrails']): string | undefined => {const host: HostCRD = { ...makeHost(), spec: { ...makeHost().spec, guardrails } }@@ -1022,13 +1018,20 @@ describe('HostReconciler.buildDeployment — SharedFileSystem mounts', () => {'clerum.io/guardrails-revision']}- const a = revFor({ hooks: { preCall: [{ id: 'h1', digest: 'sha256:abc' }] } })- const aAgain = revFor({ hooks: { preCall: [{ id: 'h1', digest: 'sha256:abc' }] } })- const b = revFor({ hooks: { preCall: [{ id: 'h2', digest: 'sha256:def' }] } })- // Same guardrails → same hash: no spurious rolls.- expect(a).toBe(aAgain)- // Changed guardrails → new hash → the pod template flips → rolling restart.- expect(a).not.toBe(b)+ // Same content, reordered keys at BOTH the top level (hooks/builtins) and the+ // hook ref (id/digest). A shallow canonicalization would flip the hash here+ // and roll the pod for nothing; the deep-stable hash must return the same.+ const a = revFor({+ hooks: { preCall: [{ id: 'h1', digest: 'sha256:abc' }] },+ builtins: [{ type: 'token-trim' }],+ })+ const reordered = revFor({+ builtins: [{ type: 'token-trim' }],+ hooks: { preCall: [{ digest: 'sha256:abc', id: 'h1' }] },+ })+ const changed = revFor({ hooks: { preCall: [{ id: 'h2', digest: 'sha256:def' }] } })+ expect(a).toBe(reordered) // reorder only → same hash → no spurious roll+ expect(a).not.toBe(changed) // real change → new hash → rolling restartexpect(a).toMatch(/^[0-9a-f]{64}$/)})diff --git a/host-context-controller/src/hostReconciler.ts b/host-context-controller/src/hostReconciler.tsindex a0fe92524..3ed4e9dcc 100644--- a/host-context-controller/src/hostReconciler.ts+++ b/host-context-controller/src/hostReconciler.ts@@ -202,6 +202,29 @@ const RUNTIME_TOKEN_REVISION_ANNOTATION = 'clerum.io/runtime-token-revision'// flip the template → rolling restart → mcp-host re-reads guardrails at boot.// Mirrors the runtime-token / credentials revision annotations.const GUARDRAILS_REVISION_ANNOTATION = 'clerum.io/guardrails-revision'++/**+ * Deep, key-sorted JSON for a stable content hash. Object keys are sorted at+ * EVERY level — unlike `canonicalStringify`, which sorts only the top level —+ * so a guardrails block that differs only in nested key order (e.g. the API+ * returning `hooks` phases or a hook ref's fields in a different order) hashes+ * identically and does not roll mcp-host for nothing. Array order is PRESERVED:+ * hook precedence within a phase is semantic, so reordering it is a real change.+ */+function deepStableStringify(value: unknown): string {+ const norm = (v: unknown): unknown => {+ if (Array.isArray(v)) return v.map(norm)+ if (v && typeof v === 'object') {+ const out: Record<string, unknown> = {}+ for (const k of Object.keys(v as Record<string, unknown>).sort()) {+ out[k] = norm((v as Record<string, unknown>)[k])+ }+ return out+ }+ return v+ }+ return JSON.stringify(norm(value))+}const RUNTIME_TOKEN_SECRET_REVISION_ANNOTATION = 'clerum.io/runtime-token-secret-revision'const RUNTIME_TOKEN_ISSUED_AT_ANNOTATION = 'clerum.io/runtime-token-issued-at'const RUNTIME_TOKEN_REFRESH_EXPIRES_AT_ANNOTATION = 'clerum.io/runtime-token-refresh-expires-at'@@ -2370,7 +2393,7 @@ export class HostReconciler {// (when guardrails is absent the annotation is simply omitted).if (host.spec.guardrails) {podAnnotations[GUARDRAILS_REVISION_ANNOTATION] = createHash('sha256')- .update(canonicalStringify(host.spec.guardrails as unknown as Record<string, unknown>))+ .update(deepStableStringify(host.spec.guardrails)).digest('hex')}