Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
/**
* LLM-model impact enumeration (spec Fase 3). Enumerates every LIVE reference to
* an operator-allowlist `(provider, model)` pair, so a destructive allowlist
* mutation (DELETE, or a PUT that disables the model) can warn the operator
* about the Hosts/grants it would silently invalidate instead of breaking them
* in the dark.
*
* This feeds a SAFETY GATE: an under-report lets the operator disable a still-
* referenced model believing it is free — exactly the silent breakage the phase
* exists to prevent. So the enumeration is FAIL-LOUD: if any Host LIST fails, the
* whole computation REJECTS (propagates) rather than returning a partial result,
* and the caller fails the destructive op closed.
*
* A `(provider, model)` pair is referenced from FOUR sources — a hybrid of the
* live K8s CRD store and Postgres:
* 1. Host `spec.model` (the primary model the Host defaults to) [CRD]
* 2. Host `spec.allowedModels[]` (the per-Host offered subset) [CRD]
* 3. Host `spec.llmPolicy.fallbacks[]` (the provider-fallback policy) [CRD]
* 4. `plugin_workload_sdk_grants.allowed_models` (grant model allowlist) [PG]
*
* OUT OF SCOPE by design (spec §3.2 + §5): grant `prompt_targets` are NOT
* enumerated. The spec limits the grant impact surface to `allowed_models` (§3.2)
* and excludes promptBridge from carrying a warning surface (§5). References that
* exist only through `prompt_targets` are intentionally not reported here — this
* is a deliberate scope boundary, not a missing source.
*
* NAMESPACE COVERAGE. Host CRDs live in the operator's host namespace(s). This
* module enumerates the SAME set the canonical host fan-out uses — the injected
* `hostNamespaces` (built from `config.hostsNamespace` + the control-api default
* namespace, mirroring `ResourceService.listNamespacesForPlural('hosts')`) — and
* LISTs each ONE BY ONE via `listResource('hosts', ns)`. It deliberately does NOT
* use the `namespace='*'` sentinel: `ResourceService` swallows per-namespace LIST
* errors on that path (`catch {}`), which would silently under-report. The
* per-namespace path propagates, giving the fail-loud guarantee above. Every
* admin write pins Hosts to `config.hostsNamespace` (`enforceNamespace`), so this
* set is the full universe a Host can occupy. Cost: O(#namespaces) LIST calls,
* each O(#Hosts).
*
* The GRANT match is by MODEL NAME ONLY, not `(provider, model)`. The grant
* `allowed_models` column is a provider-LESS flat model-name list and is NOT
* enforced to hold only models of the grant's `provider` column (the write-gate
* validates `prompt_targets` per-provider, but `allowed_models` is passed through
* free-form and can span providers). Filtering by `provider` would therefore
* UNDER-report — the unsafe direction for a safety gate. Matching by model name
* may over-report a same-named model under a different provider (added operator
* friction, never silent breakage), which is the fail-safe trade-off.
*
* ONE module, TWO callers (regla D4): the `?force` gate on PUT/DELETE
* (`routes/admin/llmModels.ts`) and, later, `GET /admin/attention` (Fase 5).
* Neither reconstructs the impact — both call `computeModelImpact`.
*/
import type { DbClient } from '../db.js'
import {
type HostModelRole,
enumerateHostModelReferences,
} from '../routes/admin/hostModelReferences.js'
import { offeredKey } from '../routes/admin/modelAllowlistTolerance.js'
import { isPlainObject } from '../utils/isPlainObject.js'
import { type PluginWorkloadSdkGrant, listGrantsReferencingModel } from './pluginWorkloadSdkDb.js'
/**
* Which Host spec source referenced the pair. A Host may match in several.
* Re-exported from the shared enumeration module (regla D4) so existing importers
* of this symbol from `llmModelImpact` keep working.
*/
export type { HostModelRole }
/** A Host CR that references the pair, with the roles it matched in. */
export interface HostModelReference {
namespace: string
name: string
roles: HostModelRole[]
}
/** A grant that references the pair through its `allowed_models` list. */
export interface GrantModelReference {
id: string
recipeNamespace: string
recipeName: string
capabilityFamily: string
}
/** The enumerated live references to a `(provider, model)` pair. */
export interface ModelImpact {
provider: string
model: string
hostsAffected: HostModelReference[]
grantsAffected: GrantModelReference[]
}
/**
* Injectable sources so the enumeration stays unit-testable without a real K8s
* client or DB. Both callers build these from the real producers via
* `modelImpactSourcesFromGateway`.
*/
export interface ModelImpactSources {
/** The exact set of namespaces a Host can occupy (the canonical host set). */
hostNamespaces: string[]
/**
* LIST Hosts in ONE namespace. MUST propagate (reject) on failure — the
* enumeration relies on that for its fail-loud/fail-closed guarantee.
*/
listHostsInNamespace: (namespace: string) => Promise<unknown[]>
/** Grants whose `allowed_models` list contains `model` (provider-less match). */
listGrantsForModel: (model: string) => Promise<PluginWorkloadSdkGrant[]>
}
/** Minimal gateway surface this module needs — a per-namespace Host LIST. */
interface HostListGateway {
listResource: (plural: 'hosts', namespace?: string) => Promise<unknown[]>
}
/**
* Wire the impact sources to the real producers: live per-namespace Host LIST via
* the K8s gateway (NO `'*'` — see the fail-loud rationale above) and the grant
* SQL query. `hostNamespaces` is supplied by the caller from config so the single
* source of truth for "where Hosts live" stays in one place.
*/
export function modelImpactSourcesFromGateway(
gateway: HostListGateway,
hostNamespaces: string[]
): ModelImpactSources {
// Delegates with `db` unset so the grant query defaults to the global pool —
// ONE derivation of the sources (regla D4), shared with the transactional form.
return modelImpactSourcesFromGatewayTx(gateway, hostNamespaces)
}
/**
* The impact sources for the R1-H3 reductor path: the grant query is bound to the
* caller's TRANSACTION client `db` (so the impact recompute happens under the
* advisory lock, on the same connection), while the Host LIST still reads K8s LIVE
* (a consistent etcd read — never a watch-cache, adenda A5 — so the reductor sees
* a CR a concurrent host-create just committed). Passing `db` omitted reproduces
* the non-transactional form exactly (grant query on the pool). `computeModelImpact`
* and its fail-loud contract are untouched.
*/
export function modelImpactSourcesFromGatewayTx(
gateway: HostListGateway,
hostNamespaces: string[],
db?: DbClient
): ModelImpactSources {
return {
hostNamespaces,
listHostsInNamespace: namespace => gateway.listResource('hosts', namespace),
listGrantsForModel: model => listGrantsReferencingModel(model, db),
}
}
/**
* The roles in which a Host spec references the TARGET `(provider, model)` pair.
* Provider-aware match: keeps only the shared enumeration entries whose key
* equals `targetKey` (the same NUL-separated `offeredKey` the write-gate uses, so
* a model id containing spaces can never collide with a distinct pair), deduped
* so each role appears at most once, in spec order (primary, allowedModels,
* fallback). Empty when the Host does not reference the target.
*
* The location enumeration itself lives in `enumerateHostModelReferences` (regla
* D4), shared verbatim with the tolerance seam's `storedRoleSets`. This caller's
* own concern — layered on top — is target-filtering + role dedup.
*/
function hostRolesReferencing(spec: unknown, targetKey: string): HostModelRole[] {
const roles: HostModelRole[] = []
const seen = new Set<HostModelRole>()
for (const ref of enumerateHostModelReferences(spec)) {
if (ref.key !== targetKey || seen.has(ref.role)) continue
seen.add(ref.role)
roles.push(ref.role)
}
return roles
}
/**
* Enumerate every live reference to `(provider, model)` across the four sources.
* Aggregation over the injected sources — its only I/O is the Host LIST per
* namespace and the grant query, both of which it lets REJECT (fail-loud). No
* try/catch: a partial enumeration must never be returned to a safety gate.
* Shared verbatim by the `?force` gate and the Fase 5 attention endpoint.
*/
export async function computeModelImpact(
provider: string,
model: string,
sources: ModelImpactSources
): Promise<ModelImpact> {
const targetKey = offeredKey(provider, model)
const hostsAffected: HostModelReference[] = []
for (const namespace of sources.hostNamespaces) {
// No catch: a failed LIST propagates so the caller fails the destructive op
// CLOSED instead of acting on a partial (under-reported) impact.
const hosts = await sources.listHostsInNamespace(namespace)
for (const host of hosts) {
if (!isPlainObject(host)) continue
const roles = hostRolesReferencing(host.spec, targetKey)
if (roles.length === 0) continue
const metadata = isPlainObject(host.metadata) ? host.metadata : {}
hostsAffected.push({
namespace: typeof metadata.namespace === 'string' ? metadata.namespace : namespace,
name: typeof metadata.name === 'string' ? metadata.name : '',
roles,
})
}
}
const grants = await sources.listGrantsForModel(model)
const grantsAffected: GrantModelReference[] = grants.map(grant => ({
id: grant.id,
recipeNamespace: grant.recipeNamespace,
recipeName: grant.recipeName,
capabilityFamily: grant.capabilityFamily,
}))
return { provider, model, hostsAffected, grantsAffected }
}
/** True when the pair has at least one live Host or grant reference. */
export function modelImpactHasReferences(impact: ModelImpact): boolean {
return impact.hostsAffected.length > 0 || impact.grantsAffected.length > 0
}