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.tsindex 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.tsindex 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.tsindex 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')