Skip to content

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.json
index 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.json
index 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.ts
index 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 restart
expect(a).toMatch(/^[0-9a-f]{64}$/)
})
diff --git a/host-context-controller/src/hostReconciler.ts b/host-context-controller/src/hostReconciler.ts
index 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')
}