Skip to content

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

TypeScript

refactor(#408): share handshake annotation keys via @clerum/network-policy-core

Alfredo Lopez857e6b930a79
diff --git a/host-context-controller/package-lock.json b/host-context-controller/package-lock.json
index 443829a72..43b739e7a 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 7c6a6a9ba..4184347bd 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/reconciler.ts b/host-context-controller/src/reconciler.ts
index 9908c347b..b83fc70a1 100644
--- a/host-context-controller/src/reconciler.ts
+++ b/host-context-controller/src/reconciler.ts
@@ -13,6 +13,11 @@ import * as k8s from '@kubernetes/client-node'
import { IntOrString } from '@kubernetes/client-node/dist/types.js'
import { createHash } from 'crypto'
import { classifyPluginImage } from '@clerum/image-policy'
+import {
+ NETWORK_READY_ANNOTATION,
+ NETWORK_READY_GENERATION_ANNOTATION,
+ PRE_DEPLOY_ANNOTATION,
+} from '@clerum/network-policy-core'
import { isWorkflowRecipeDefaultAllowedCapability } from '@clerum/workflow-recipe-capability-policy'
import { config } from './config'
import { MANAGED_BY_LABEL, MANAGED_BY_VALUE, MCPSERVER_LABEL } from './constants'
@@ -71,12 +76,10 @@ type McpServerReconcilerDeps = {
networkingApi?: k8s.NetworkingV1Api
}
-// G2: Pre-deploy handshake constants
-const PRE_DEPLOY_ANNOTATION = 'clerum.io/pre-deploy'
-const NETWORK_READY_ANNOTATION = 'clerum.io/network-ready'
-// Issue #408: stamp the generation observed when acking so WRC can reject a stale
-// ack carried over from a previous generation.
-const NETWORK_READY_GENERATION_ANNOTATION = 'clerum.io/network-ready-observed-generation'
+// G2: Pre-deploy handshake constants — imported from @clerum/network-policy-core
+// (single source of truth shared with WRC; a divergence is a compile error rather
+// than a silent 30s fail-open timeout). clerum.io/network-ready-observed-generation
+// (Issue #408) is the generation HCC stamps when acking, so WRC can reject a stale ack.
// Issue #223: sha256 of the envSecret content, carried on the POD TEMPLATE (not
// the Deployment object) so that changing it changes the pod template hash and
diff --git a/packages/network-policy-core/index.cjs b/packages/network-policy-core/index.cjs
index a4b8f20bb..5192d454c 100644
--- a/packages/network-policy-core/index.cjs
+++ b/packages/network-policy-core/index.cjs
@@ -9,6 +9,14 @@ const STATE_ANNOTATION = 'clerum.io/egress-fqdn-state'
const TARGETS_ANNOTATION = 'clerum.io/egress-fqdn-targets'
const RESOLVED_AT_ANNOTATION = 'clerum.io/egress-fqdn-resolved-at'
+// Pre-deploy network-readiness handshake keys (WRC producer/consumer, HCC producer).
+// Shared here so WRC (workflow-recipes) and HCC (host-context-controller) derive the
+// exact same literals — a divergence becomes a compile error, not a silent 30s
+// fail-open timeout. Consumed by both services' reconcilers.
+const PRE_DEPLOY_ANNOTATION = 'clerum.io/pre-deploy'
+const NETWORK_READY_ANNOTATION = 'clerum.io/network-ready'
+const NETWORK_READY_GENERATION_ANNOTATION = 'clerum.io/network-ready-observed-generation'
+
const DEFAULT_PROTOCOL = 'TCP'
const LEGACY_PORT = 443
// Upper bound on a DNS TTL (ms) folded into the window (audit M2). A hostile or
@@ -400,6 +408,9 @@ module.exports = {
STATE_ANNOTATION,
TARGETS_ANNOTATION,
RESOLVED_AT_ANNOTATION,
+ PRE_DEPLOY_ANNOTATION,
+ NETWORK_READY_ANNOTATION,
+ NETWORK_READY_GENERATION_ANNOTATION,
emptyState,
reconcileEgressState,
stateHash,
diff --git a/packages/network-policy-core/index.d.ts b/packages/network-policy-core/index.d.ts
index 17369e5d9..9972b2644 100644
--- a/packages/network-policy-core/index.d.ts
+++ b/packages/network-policy-core/index.d.ts
@@ -130,6 +130,11 @@ export declare const STATE_ANNOTATION: string
export declare const TARGETS_ANNOTATION: string
export declare const RESOLVED_AT_ANNOTATION: string
+/** Pre-deploy network-readiness handshake annotation keys (shared by WRC and HCC). */
+export declare const PRE_DEPLOY_ANNOTATION: string
+export declare const NETWORK_READY_ANNOTATION: string
+export declare const NETWORK_READY_GENERATION_ANNOTATION: string
+
/**
* Classify a DNS failure as 'transient' (resolver/upstream temporarily
* unavailable → fail-static freeze, H1) or 'permanent' (genuine no-records →
diff --git a/workflow-recipes/package-lock.json b/workflow-recipes/package-lock.json
index 98819da6e..2c4905226 100644
--- a/workflow-recipes/package-lock.json
+++ b/workflow-recipes/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "workload-recipes-controller",
- "version": "0.1.297",
+ "version": "0.1.298",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "workload-recipes-controller",
- "version": "0.1.297",
+ "version": "0.1.298",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@aws-sdk/client-s3": "^3.1009.0",
diff --git a/workflow-recipes/package.json b/workflow-recipes/package.json
index 2e53e7214..81a015220 100644
--- a/workflow-recipes/package.json
+++ b/workflow-recipes/package.json
@@ -1,6 +1,6 @@
{
"name": "workload-recipes-controller",
- "version": "0.1.297",
+ "version": "0.1.298",
"description": "Workload Recipes Controller (WRC) - WorkloadRecipe lifecycle management and MCP server interface",
"main": "dist/main.js",
"engines": {
diff --git a/workflow-recipes/src/reconciler/mcpDelegation.ts b/workflow-recipes/src/reconciler/mcpDelegation.ts
index 95e78d07b..21b5f8168 100644
--- a/workflow-recipes/src/reconciler/mcpDelegation.ts
+++ b/workflow-recipes/src/reconciler/mcpDelegation.ts
@@ -10,6 +10,11 @@
* - stdio workloads: managed: true — HCC owns Deployment (stdio-bridge sidecar)
*/
import * as k8s from '@kubernetes/client-node'
+import {
+ NETWORK_READY_ANNOTATION,
+ NETWORK_READY_GENERATION_ANNOTATION,
+ PRE_DEPLOY_ANNOTATION,
+} from '@clerum/network-policy-core'
import {
EVENFIRE_REGISTRY_PULL_SECRET_NAME,
isPlatformRegistryImage,
@@ -787,11 +792,12 @@ export async function ensureRecipeContext(
*
* See: PHASE-9-PRE-PRODUCTION-HARDENING.md §GAP 14, Option C
*/
-export const PRE_DEPLOY_ANNOTATION = 'clerum.io/pre-deploy'
-export const NETWORK_READY_ANNOTATION = 'clerum.io/network-ready'
-// Issue #408: HCC stamps the McpServer generation it observed when acking network
-// readiness, so WRC can reject a stale ack carried over from a prior generation.
-export const NETWORK_READY_GENERATION_ANNOTATION = 'clerum.io/network-ready-observed-generation'
+// Handshake annotation keys now live in @clerum/network-policy-core (single source of
+// truth shared with HCC — a divergence is a compile error, not a silent 30s timeout).
+// Re-exported here so existing WRC consumers keep importing them from this module.
+// clerum.io/network-ready-observed-generation (Issue #408) is the generation HCC
+// stamps when acking, so WRC can reject a stale ack from a prior generation.
+export { PRE_DEPLOY_ANNOTATION, NETWORK_READY_ANNOTATION, NETWORK_READY_GENERATION_ANNOTATION }
const NETWORK_READY_POLL_INTERVAL_MS = 1_000
const NETWORK_READY_TIMEOUT_MS = 30_000
diff --git a/workflow-recipes/src/reconciler/specHash.ts b/workflow-recipes/src/reconciler/specHash.ts
index b0ab12ffd..40df77839 100644
--- a/workflow-recipes/src/reconciler/specHash.ts
+++ b/workflow-recipes/src/reconciler/specHash.ts
@@ -1,4 +1,5 @@
import { createHash } from 'node:crypto'
+import { PRE_DEPLOY_ANNOTATION } from '@clerum/network-policy-core'
/**
* Annotation that records a hash of the recipe-derived manifest WRC last applied
@@ -34,10 +35,11 @@ export const SPEC_HASH_ANNOTATION = 'clerum.io/spec-hash'
* 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).
+ * the object — only from the hash. The key comes from the shared
+ * `@clerum/network-policy-core` constant (the same one WRC and HCC use), so it
+ * cannot drift; specHash.test.ts still pins the exclusion-list membership.
*/
-export const HASH_EXCLUDED_ANNOTATIONS = ['clerum.io/pre-deploy'] as const
+export const HASH_EXCLUDED_ANNOTATIONS = [PRE_DEPLOY_ANNOTATION] as const
// Loose, class-compatible shape: K8s client model classes (V1Deployment, …) have
// `metadata?: V1ObjectMeta` with `annotations?: { [k]: string }`, so they satisfy