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.jsonindex 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.jsonindex 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.tsindex 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?: stringnamespace?: stringgeneration?: number+ uid?: stringannotations?: 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}$/iexport class HccAdministrativeOutcomeBindingResolver implements AdministrativeOperationBindingResolver {@@ -79,7 +88,10 @@ export class HccAdministrativeOutcomeBindingResolver implements AdministrativeOphost.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 nullconst operationId = metadata.annotations?.[ADMINISTRATIVE_INTENT_ANNOTATION]@@ -143,6 +155,7 @@ function parseHostStatusRef(value: string | undefined): {namespace: stringname: stringgeneration: number+ uid: string} | null {if (!value) return nullconst 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.tsindex 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.tsindex 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 AdministrativeEventSubmitterPrincipalV1const 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.jsonindex 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.jsonindex 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.tsindex 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.tsindex 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: stringoccurredAt: 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 AdministrativeOutcooccurredAt: 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.tsindex 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.tsindex 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 fetchconst administrativeOutcomeReporter = new BoundedAdministrativeOutcomeReporter({