Skip to content

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

TypeScript

fix(hcc,control-api): bind administrative outcomes by Host uid

Alfredo Lopez4bf93b4221d0
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index 5d2665b68..c76225829 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.587",
+ "version": "0.1.588",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.587",
+ "version": "0.1.588",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/grok-provider-attempt-contract": "file:../packages/grok-provider-attempt-contract",
diff --git a/control-api/package.json b/control-api/package.json
index 9ac84821c..d3cc0edd9 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.587",
+ "version": "0.1.588",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/src/services/tracing/adminOperationBindingResolver.ts b/control-api/src/services/tracing/adminOperationBindingResolver.ts
index 1ca7fe5dc..3fe769dff 100644
--- a/control-api/src/services/tracing/adminOperationBindingResolver.ts
+++ b/control-api/src/services/tracing/adminOperationBindingResolver.ts
@@ -22,12 +22,21 @@ type HostResource = {
name?: string
namespace?: string
generation?: number
+ uid?: string
annotations?: Record<string, string>
}
}
+/**
+ * `host:<ns>/<name>:generation=<n>:uid=<uuid>`. The uid is required: a Host
+ * deleted and recreated under the same name restarts at generation 1, so
+ * namespace/name/generation alone can name two different objects (#694). The
+ * emitter is host-context-controller/src/administrativeOutcomeReporter.ts,
+ * which builds this literal; the two live in different packages and cannot
+ * import each other, so each side pins the same example string in its tests.
+ */
const STATUS_REF =
- /^host:([a-z0-9]([-a-z0-9]*[a-z0-9])?)\/([a-z0-9]([-a-z0-9]*[a-z0-9])?):generation=([1-9][0-9]*)$/
+ /^host:([a-z0-9]([-a-z0-9]*[a-z0-9])?)\/([a-z0-9]([-a-z0-9]*[a-z0-9])?):generation=([1-9][0-9]*):uid=([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$/
const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
export class HccAdministrativeOutcomeBindingResolver implements AdministrativeOperationBindingResolver {
@@ -79,7 +88,10 @@ export class HccAdministrativeOutcomeBindingResolver implements AdministrativeOp
host.kind !== 'Host' ||
metadata?.name !== reference.name ||
metadata.namespace !== reference.namespace ||
- metadata.generation !== reference.generation
+ metadata.generation !== reference.generation ||
+ // The live object must be the one the reporter observed, not a
+ // same-name successor that reached the same generation (#694).
+ metadata.uid !== reference.uid
)
return null
const operationId = metadata.annotations?.[ADMINISTRATIVE_INTENT_ANNOTATION]
@@ -143,6 +155,7 @@ function parseHostStatusRef(value: string | undefined): {
namespace: string
name: string
generation: number
+ uid: string
} | null {
if (!value) return null
const match = STATUS_REF.exec(value)
@@ -151,6 +164,7 @@ function parseHostStatusRef(value: string | undefined): {
namespace: match[1]!,
name: match[3]!,
generation: Number(match[5]),
+ uid: match[6]!,
}
}
diff --git a/control-api/test/services.adminOperationBindingResolver.test.ts b/control-api/test/services.adminOperationBindingResolver.test.ts
index a898a6f9b..7e535fcea 100644
--- a/control-api/test/services.adminOperationBindingResolver.test.ts
+++ b/control-api/test/services.adminOperationBindingResolver.test.ts
@@ -9,11 +9,21 @@ const principal = {
allowedKinds: ['linked_outcome'],
} as const
+/**
+ * Cross-service format contract (#694). `STATUS_REF_FROM_HCC` is the exact
+ * string host-context-controller emits
+ * (host-context-controller/src/administrativeOutcomeReporter.ts), which pins
+ * this same literal in its own test. The two packages cannot import each
+ * other, so change one side and the other side's test fails.
+ */
+const HOST_UID = '6f1c2f3a-2f4b-4d3a-9b2e-7c0d1a5e8b44'
+const STATUS_REF_FROM_HCC = `host:mcp-host/chatllm:generation=7:uid=${HOST_UID}`
+
const event = {
kind: 'linked_outcome' as const,
sourceEventId: 'outcome-1',
occurredAt: '2026-07-11T10:00:00.000Z',
- sourceStatusRef: 'host:mcp-host/chatllm:generation=7',
+ sourceStatusRef: STATUS_REF_FROM_HCC,
payload: { resource_class: 'Host', status: 'succeeded' },
}
@@ -35,7 +45,8 @@ const intentAttribution = {
function host(
operationId = '11111111-1111-4111-8111-111111111111',
generation = 7,
- intentGeneration = generation
+ intentGeneration = generation,
+ uid = HOST_UID
) {
return {
apiVersion: 'clerum.io/v1alpha1',
@@ -44,6 +55,7 @@ function host(
name: 'chatllm',
namespace: 'mcp-host',
generation,
+ uid,
annotations: {
'clerum.io/administrative-intent-id': operationId,
'clerum.io/administrative-intent-generation': String(intentGeneration),
@@ -90,6 +102,10 @@ describe('HccAdministrativeOutcomeBindingResolver', () => {
['stale intent annotation', host(undefined, 7, 6), true],
['invalid annotation', host('caller-value'), true],
['missing intent', host(), false],
+ // A Host deleted and recreated under the same name reaches the same
+ // generation and carries the same intent annotation; only the uid differs
+ // (#694).
+ ['a same-name Host with another uid', host(undefined, 7, 7, 'another-host-uid'), true],
] as const)('rejects %s', async (_label, resource, hasIntent) => {
const resolver = new HccAdministrativeOutcomeBindingResolver(
{ getResource: vi.fn(), listResource: vi.fn().mockResolvedValue([resource]) },
@@ -111,4 +127,34 @@ describe('HccAdministrativeOutcomeBindingResolver', () => {
)
await expect(resolver.resolve(principal, event)).resolves.toBeNull()
})
+
+ it('refuses a sourceStatusRef without the uid suffix (#694)', async () => {
+ const resolver = new HccAdministrativeOutcomeBindingResolver(
+ { getResource: vi.fn(), listResource: vi.fn().mockResolvedValue([host()]) },
+ {
+ findHostIntent: vi.fn(),
+ findHostIntents: vi
+ .fn()
+ .mockResolvedValue(
+ new Map([
+ ['11111111-1111-4111-8111-111111111111:mcp-host:mcp-host/chatllm', intentAttribution],
+ ])
+ ),
+ }
+ )
+
+ // Batched with the current format so the null below cannot come from a
+ // resolver that refuses everything: the same call binds the other event.
+ const [legacy, current] = await resolver.resolveMany(principal, [
+ {
+ ...event,
+ sourceEventId: 'outcome-legacy',
+ sourceStatusRef: 'host:mcp-host/chatllm:generation=7',
+ },
+ event,
+ ])
+
+ expect(legacy).toBeNull()
+ expect(current).toMatchObject({ targetRef: 'mcp-host/chatllm', outcome: 'succeeded' })
+ })
})
diff --git a/control-api/test/services.tracingAppends.test.ts b/control-api/test/services.tracingAppends.test.ts
index 291bbf150..e258919ad 100644
--- a/control-api/test/services.tracingAppends.test.ts
+++ b/control-api/test/services.tracingAppends.test.ts
@@ -371,6 +371,9 @@ describe('governed append idempotency', () => {
})
describe('HCC linked outcomes re-observed at a later time (#327)', () => {
+ // The identity HCC emits since #694: the Host uid is in both the dedupe
+ // key and the status ref.
+ const HOST_UID = '6f1c2f3a-2f4b-4d3a-9b2e-7c0d1a5e8b44'
const hccAdminPrincipal = {
kind: 'hcc_internal_control',
sourceService: 'host-context-controller',
@@ -380,10 +383,10 @@ describe('governed append idempotency', () => {
} as const satisfies AdministrativeEventSubmitterPrincipalV1
const hccOutcome = {
kind: 'linked_outcome' as const,
- sourceEventId: `hcc-admin-outcome:${adminBinding.operationId}:3:succeeded`,
+ sourceEventId: `hcc-admin-outcome-v2:${adminBinding.operationId}:3:${HOST_UID}:succeeded`,
occurredAt: '2026-07-10T09:59:59.000Z',
reasonCode: 'reconciled',
- sourceStatusRef: 'host:mcp-host/chatllm:generation=3',
+ sourceStatusRef: `host:mcp-host/chatllm:generation=3:uid=${HOST_UID}`,
payload: { resource_class: 'Host', status: 'succeeded' },
}
const service = () =>
diff --git a/host-context-controller/package-lock.json b/host-context-controller/package-lock.json
index 8e2309e28..23580e225 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.341",
+ "version": "0.1.342",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-host-context-controller",
- "version": "0.1.341",
+ "version": "0.1.342",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@clerum/codex-catalog-projection": "file:../packages/codex-catalog-projection",
diff --git a/host-context-controller/package.json b/host-context-controller/package.json
index 543c8b462..1c1e7faec 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.341",
+ "version": "0.1.342",
"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/administrativeOutcomeReporter.test.ts b/host-context-controller/src/administrativeOutcomeReporter.test.ts
index 7aaf39516..8d739b73f 100644
--- a/host-context-controller/src/administrativeOutcomeReporter.test.ts
+++ b/host-context-controller/src/administrativeOutcomeReporter.test.ts
@@ -6,6 +6,18 @@ import {
} from './administrativeOutcomeReporter'
import { administrativeOutcomeReporterTotal } from './metrics'
+/**
+ * Cross-service format contract (#694). `EXPECTED_STATUS_REF` is the exact
+ * string control-api's `STATUS_REF` must parse
+ * (control-api/src/services/tracing/adminOperationBindingResolver.ts). The two
+ * packages cannot import each other, so control-api pins this same literal in
+ * control-api/test/services.adminOperationBindingResolver.test.ts. Change one
+ * side and the other side's test fails.
+ */
+const HOST_UID = '6f1c2f3a-2f4b-4d3a-9b2e-7c0d1a5e8b44'
+const HOST_REF = { name: 'chatllm', namespace: 'mcp-host', generation: 7, uid: HOST_UID }
+const EXPECTED_STATUS_REF = `host:mcp-host/chatllm:generation=7:uid=${HOST_UID}`
+
describe('createAdministrativeOutcomeReporter', () => {
it('does not construct a reporter when governed tracing is disabled', () => {
expect(
@@ -35,7 +47,7 @@ describe('BoundedAdministrativeOutcomeReporter', () => {
reporter.enqueueHostOutcome({
sourceEventId: 'hcc-admin-outcome:op-1:7:succeeded',
occurredAt: '2026-07-11T10:00:00.000Z',
- hostRef: { name: 'chatllm', namespace: 'mcp-host', generation: 7 },
+ hostRef: HOST_REF,
outcome: 'succeeded',
reasonCode: 'reconciled',
})
@@ -45,7 +57,7 @@ describe('BoundedAdministrativeOutcomeReporter', () => {
expect(body.events[0]).toEqual(
expect.objectContaining({
kind: 'linked_outcome',
- sourceStatusRef: 'host:mcp-host/chatllm:generation=7',
+ sourceStatusRef: EXPECTED_STATUS_REF,
payload: { resource_class: 'Host', status: 'succeeded' },
})
)
@@ -63,7 +75,7 @@ describe('BoundedAdministrativeOutcomeReporter', () => {
reporter.enqueueHostOutcome({
sourceEventId: 'outcome-1',
occurredAt: '2026-07-11T10:00:00.000Z',
- hostRef: { name: 'chatllm', namespace: 'mcp-host', generation: 7 },
+ hostRef: HOST_REF,
outcome: 'failed',
reasonCode: 'reconcile_failed',
})
@@ -83,7 +95,7 @@ describe('BoundedAdministrativeOutcomeReporter', () => {
reporter.enqueueHostOutcome({
sourceEventId: 'outcome-queued',
occurredAt: '2026-07-11T10:00:00.000Z',
- hostRef: { name: 'chatllm', namespace: 'mcp-host', generation: 7 },
+ hostRef: HOST_REF,
outcome: 'succeeded',
reasonCode: 'reconciled',
})
@@ -95,7 +107,7 @@ describe('BoundedAdministrativeOutcomeReporter', () => {
expect.objectContaining({
sourceEventId: 'outcome-queued',
kind: 'linked_outcome',
- sourceStatusRef: 'host:mcp-host/chatllm:generation=7',
+ sourceStatusRef: EXPECTED_STATUS_REF,
})
)
})
@@ -113,7 +125,7 @@ describe('BoundedAdministrativeOutcomeReporter', () => {
reporter.enqueueHostOutcome({
sourceEventId: 'outcome-failed',
occurredAt: '2026-07-11T10:00:00.000Z',
- hostRef: { name: 'chatllm', namespace: 'mcp-host', generation: 7 },
+ hostRef: HOST_REF,
outcome: 'failed',
reasonCode: 'reconcile_failed',
})
@@ -128,7 +140,7 @@ function outcome(sourceEventId: string): AdministrativeHostOutcomeProjection {
return {
sourceEventId,
occurredAt: '2026-09-18T10:00:00.000Z',
- hostRef: { name: 'chatllm', namespace: 'mcp-host', generation: 7 },
+ hostRef: HOST_REF,
outcome: 'succeeded',
reasonCode: 'reconciled',
}
diff --git a/host-context-controller/src/administrativeOutcomeReporter.ts b/host-context-controller/src/administrativeOutcomeReporter.ts
index 40f2881ec..b14929587 100644
--- a/host-context-controller/src/administrativeOutcomeReporter.ts
+++ b/host-context-controller/src/administrativeOutcomeReporter.ts
@@ -7,7 +7,13 @@ import { signInternalControlJwt } from './utils/internalControlSigner'
export type AdministrativeHostOutcomeProjection = {
sourceEventId: string
occurredAt: string
- hostRef: { name: string; namespace: string; generation: number }
+ /**
+ * `uid` is required: a Host deleted and recreated under the same name
+ * restarts at generation 1, so namespace/name/generation alone can name two
+ * different objects. control-api resolves the binding against the live
+ * object's metadata.uid and refuses the reference without it (#694).
+ */
+ hostRef: { name: string; namespace: string; generation: number; uid: string }
outcome: 'succeeded' | 'failed'
reasonCode: string
}
@@ -136,7 +142,11 @@ export class BoundedAdministrativeOutcomeReporter implements AdministrativeOutco
occurredAt: projection.occurredAt,
kind: 'linked_outcome',
reasonCode: projection.reasonCode,
- sourceStatusRef: `host:${projection.hostRef.namespace}/${projection.hostRef.name}:generation=${projection.hostRef.generation}`,
+ // Parsed by STATUS_REF in
+ // control-api/src/services/tracing/adminOperationBindingResolver.ts.
+ // The two packages cannot import each other, so each side pins
+ // the same example string in its tests (#694).
+ sourceStatusRef: `host:${projection.hostRef.namespace}/${projection.hostRef.name}:generation=${projection.hostRef.generation}:uid=${projection.hostRef.uid}`,
payload: {
resource_class: 'Host',
status: projection.outcome,
diff --git a/host-context-controller/src/hostReconciler.ts b/host-context-controller/src/hostReconciler.ts
index 179d65cb6..01b1a2338 100644
--- a/host-context-controller/src/hostReconciler.ts
+++ b/host-context-controller/src/hostReconciler.ts
@@ -2255,10 +2255,29 @@ export class HostReconciler {
): void {
const operationId = host.annotations?.['clerum.io/administrative-intent-id']
if (!operationId || host.generation === undefined) return
+ if (host.uid === undefined) {
+ // control-api binds the outcome to the live object's metadata.uid and
+ // refuses a reference without one, so an event sent now would be a 400
+ // this reporter treats as terminal. Drop it here and say why (#694).
+ log.warn('skipping administrative outcome: Host snapshot has no uid', {
+ host: host.name,
+ namespace: host.namespace,
+ outcome,
+ })
+ return
+ }
this.administrativeOutcomeReporter?.enqueueHostOutcome({
- sourceEventId: `hcc-admin-outcome:${operationId}:${host.generation}:${outcome}`,
+ // v2: the identity gained the Host uid. sourceStatusRef feeds the
+ // server's payload hash, so keeping the v1 key would make every live
+ // key answer 409 and the uid-bearing claim would never be stored (#694).
+ sourceEventId: `hcc-admin-outcome-v2:${operationId}:${host.generation}:${host.uid}:${outcome}`,
occurredAt: this.now().toISOString(),
- hostRef: { name: host.name, namespace: host.namespace, generation: host.generation },
+ hostRef: {
+ name: host.name,
+ namespace: host.namespace,
+ generation: host.generation,
+ uid: host.uid,
+ },
outcome,
reasonCode,
})
diff --git a/host-context-controller/test/hostReconciler.test.ts b/host-context-controller/test/hostReconciler.test.ts
index b6e01bda0..378a41323 100644
--- a/host-context-controller/test/hostReconciler.test.ts
+++ b/host-context-controller/test/hostReconciler.test.ts
@@ -405,13 +405,69 @@ describe('HostReconciler', () => {
)
expect(administrativeOutcomeReporter.enqueueHostOutcome).toHaveBeenCalledWith(
expect.objectContaining({
- sourceEventId: 'hcc-admin-outcome:11111111-1111-4111-8111-111111111111:7:succeeded',
+ sourceEventId:
+ 'hcc-admin-outcome-v2:11111111-1111-4111-8111-111111111111:7:host-uid-1:succeeded',
outcome: 'succeeded',
- hostRef: { name: 'alpha-host', namespace: 'mcp-host', generation: 7 },
+ hostRef: {
+ name: 'alpha-host',
+ namespace: 'mcp-host',
+ generation: 7,
+ uid: 'host-uid-1',
+ },
})
)
})
+ it('gives a same-name recreated Host its own administrative identity (#694)', async () => {
+ const administrativeOutcomeReporter = {
+ enqueueHostOutcome: vi.fn(),
+ stop: vi.fn(async () => undefined),
+ }
+ const { reconciler } = createReconciler({ administrativeOutcomeReporter })
+ const annotations = {
+ 'clerum.io/administrative-intent-id': '11111111-1111-4111-8111-111111111111',
+ }
+ // Same name, same generation, different object: only the uid tells them
+ // apart, and the server's dedupe is keyed on this id.
+ await reconciler.reconcile(makeHost({ generation: 1, uid: 'host-uid-1', annotations }))
+ await reconciler.reconcile(makeHost({ generation: 1, uid: 'host-uid-2', annotations }))
+
+ const ids = administrativeOutcomeReporter.enqueueHostOutcome.mock.calls.map(
+ ([projection]) => projection.sourceEventId
+ )
+ // Liveness: both passes reached the reporter.
+ expect(ids).toHaveLength(2)
+ expect(new Set(ids).size).toBe(2)
+ })
+
+ it('skips the administrative outcome when the Host snapshot has no uid (#694)', async () => {
+ const warn = vi.spyOn(HostContextLogger.prototype, 'warn').mockImplementation(() => undefined)
+ onTestFinished(() => warn.mockRestore())
+ const administrativeOutcomeReporter = {
+ enqueueHostOutcome: vi.fn(),
+ stop: vi.fn(async () => undefined),
+ }
+ const { reconciler } = createReconciler({ administrativeOutcomeReporter })
+ const host = makeHost({
+ generation: 7,
+ annotations: {
+ 'clerum.io/administrative-intent-id': '11111111-1111-4111-8111-111111111111',
+ },
+ })
+ delete (host as { uid?: string }).uid
+
+ await reconciler.reconcile(host)
+
+ // Liveness: the reconcile reached the administrative branch and refused
+ // there — control-api answers a uid-less reference with a 400 this
+ // reporter treats as terminal, so the event would be lost, not retried.
+ expect(warn).toHaveBeenCalledWith(
+ 'skipping administrative outcome: Host snapshot has no uid',
+ expect.objectContaining({ host: 'alpha-host', namespace: 'mcp-host' })
+ )
+ expect(administrativeOutcomeReporter.enqueueHostOutcome).not.toHaveBeenCalled()
+ })
+
it('sends an administrative outcome once across repeated reconcile passes (#327)', async () => {
const fetchFn = vi.fn().mockResolvedValue({ ok: true }) as unknown as typeof fetch
const administrativeOutcomeReporter = new BoundedAdministrativeOutcomeReporter({