Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

fix(wrc): converge 7b/9a spec-hash by excluding pre-deploy annotation (#413)

claude[bot]2d2adfee015b
diff --git a/workflow-recipes/src/reconciler/specHash.test.ts b/workflow-recipes/src/reconciler/specHash.test.ts
index 0121fd648..a767adf7f 100644
--- a/workflow-recipes/src/reconciler/specHash.test.ts
+++ b/workflow-recipes/src/reconciler/specHash.test.ts
@@ -1,5 +1,12 @@
import { describe, expect, it } from 'vitest'
-import { SPEC_HASH_ANNOTATION, computeSpecHash, specHashUnchanged, stampSpecHash } from './specHash'
+import { PRE_DEPLOY_ANNOTATION } from './mcpDelegation'
+import {
+ HASH_EXCLUDED_ANNOTATIONS,
+ SPEC_HASH_ANNOTATION,
+ computeSpecHash,
+ specHashUnchanged,
+ stampSpecHash,
+} from './specHash'
describe('computeSpecHash', () => {
it('is stable across object key ordering (canonical)', () => {
@@ -50,6 +57,31 @@ describe('computeSpecHash', () => {
const b = { metadata: { labels: { 'clerum.io/recipe': 'r2' } }, spec: { replicas: 1 } }
expect(computeSpecHash(a)).not.toBe(computeSpecHash(b))
})
+
+ // Issue #413: WRC step 7b injects `pre-deploy: "true"` and step 9a omits it, for
+ // the SAME McpServer in the SAME pass. If the hash counted this annotation the two
+ // manifests would never converge and the idempotency gate would fire a replace
+ // twice every pass forever. Excluding it makes 7b and 9a hash identically.
+ it('ignores the pre-deploy handshake annotation (7b/9a convergence)', () => {
+ const nineA = {
+ metadata: { name: 'srv', namespace: 'mcp-server', labels: { 'clerum.io/recipe': 'r1' } },
+ spec: { transport: 'stdio' },
+ }
+ const sevenB = {
+ metadata: {
+ name: 'srv',
+ namespace: 'mcp-server',
+ labels: { 'clerum.io/recipe': 'r1' },
+ annotations: { [PRE_DEPLOY_ANNOTATION]: 'true' },
+ },
+ spec: { transport: 'stdio' },
+ }
+ expect(computeSpecHash(sevenB)).toBe(computeSpecHash(nineA))
+ })
+
+ it('keeps HASH_EXCLUDED_ANNOTATIONS in sync with PRE_DEPLOY_ANNOTATION', () => {
+ expect(HASH_EXCLUDED_ANNOTATIONS).toContain(PRE_DEPLOY_ANNOTATION)
+ })
})
describe('stampSpecHash', () => {
diff --git a/workflow-recipes/src/reconciler/specHash.ts b/workflow-recipes/src/reconciler/specHash.ts
index 8615e9851..b0ab12ffd 100644
--- a/workflow-recipes/src/reconciler/specHash.ts
+++ b/workflow-recipes/src/reconciler/specHash.ts
@@ -17,6 +17,28 @@ import { createHash } from 'node:crypto'
*/
export const SPEC_HASH_ANNOTATION = 'clerum.io/spec-hash'
+/**
+ * Annotations that record cross-controller handshake state rather than the
+ * recipe-derived desired spec, and therefore MUST be excluded from the hash.
+ *
+ * `clerum.io/pre-deploy` is the load-bearing case: WRC builds two desired
+ * manifests for the SAME McpServer in a single reconcile pass — step 7b
+ * (`preDeployMcpServers`) injects `pre-deploy: "true"` before `ensureMcpServer`,
+ * while step 9a (`delegateTransportWorkloads`) builds the manifest via
+ * `buildMcpServerManifest` WITHOUT it. If the hash counted this annotation the
+ * two manifests would hash differently and the idempotency gate would fire a
+ * `replace` twice every pass forever (never converging, because the replace
+ * carries `pre-deploy` over via the annotation merge). Excluding it lets both
+ * paths hash identically so the gate holds (zero PUTs in steady state).
+ *
+ * The annotation intentionally PERSISTS on the live object (the replace merge
+ * keeps it): HCC's network-ready re-ack guard keys off `pre-deploy === "true"`
+ * (host-context-controller/src/reconciler.ts), so it must not be stripped from
+ * the object — only from the hash. Keep this in sync with
+ * `PRE_DEPLOY_ANNOTATION` in ./mcpDelegation (asserted by specHash.test.ts).
+ */
+export const HASH_EXCLUDED_ANNOTATIONS = ['clerum.io/pre-deploy'] as const
+
// Loose, class-compatible shape: K8s client model classes (V1Deployment, …) have
// `metadata?: V1ObjectMeta` with `annotations?: { [k]: string }`, so they satisfy
// this without needing an index signature.
@@ -63,6 +85,12 @@ export function computeSpecHash(manifest: object): string {
}
if (clone.metadata.annotations && typeof clone.metadata.annotations === 'object') {
delete clone.metadata.annotations[SPEC_HASH_ANNOTATION]
+ // Handshake-state annotations (e.g. pre-deploy) are cross-controller signals,
+ // not desired spec: excluding them lets WRC's 7b (with pre-deploy) and 9a
+ // (without) manifests hash identically so the idempotency gate converges.
+ for (const key of HASH_EXCLUDED_ANNOTATIONS) {
+ delete clone.metadata.annotations[key]
+ }
// An empty annotations object must hash identically to an absent one, so that
// a freshly-built (unstamped) manifest and the same manifest after stamping
// produce the same hash (the gate's idempotency guarantee).
diff --git a/workflow-recipes/src/reconciler/workflowRecipeReconciler.ts b/workflow-recipes/src/reconciler/workflowRecipeReconciler.ts
index 7d8e76466..5336d3bec 100644
--- a/workflow-recipes/src/reconciler/workflowRecipeReconciler.ts
+++ b/workflow-recipes/src/reconciler/workflowRecipeReconciler.ts
@@ -2424,10 +2424,17 @@ export class WorkflowRecipeReconciler {
}
}
- // Step 9a: MCP delegation — finalize (Context patch + remove pre-deploy annotation)
+ // Step 9a: MCP delegation — finalize (Context patch + ensure McpServer CRDs).
// McpServer CRDs were already created in Step 7b (pre-deploy handshake).
// This step patches the Context allowlist and ensures McpServer CRDs are up-to-date.
// Same namespace invariant as Step 7b: MCP children live in mcp-server.
+ //
+ // NOTE: `pre-deploy` is deliberately NOT removed here. `buildMcpServerManifest`
+ // omits it, but the replace merge in `ensureMcpServer` carries the live object's
+ // `pre-deploy: "true"` over, so it persists — by design. HCC's network-ready
+ // re-ack guard keys off `pre-deploy === "true"`, so stripping it would break the
+ // stdio readiness handshake. The spec-hash gate excludes `pre-deploy` from the
+ // hash (see HASH_EXCLUDED_ANNOTATIONS) so 7b and 9a converge to a no-op write.
if (hasTransportWorkloads) {
if (!(await this.recipeStillActive(recipe))) {
return this.staleRecipeResult(recipe, 'MCP delegation finalization')