@open-mercato/enterprise 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7194.1.ab4fc81f82

package/src/modules/agent_orchestrator/lib/disposition/dispositionService.ts

@@ -0,0 +1,310 @@
+import type { AwilixContainer } from 'awilix'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { CommandBus, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { AgentGuardrailCheck, AgentProposal, AgentSpan } from '../../data/entities'
+import type { AutoDispositionBlock, ProposalOption } from '../../data/validators'
+import { normalizeProposalEnvelope, rankProposalOptions } from '../../data/proposalEnvelope'
+import type {
+  DisposeProposalCommandInput,
+  DisposeProposalCommandResult,
+} from '../../commands/dispose'
+import { invalidateAgentProposalCache } from '../crudCache'
+import { resolveTenantAutoApprovalPolicy } from './tenantAutoApprovalPolicy'
+import {
+  autoApprovable,
+  evaluateAutoApproval,
+  type AutoApprovalDecision,
+  type DispositionOnResult,
+  type TenantAutoApprovalPolicy,
+} from './autoApprovalPolicy'
+
+const logger = createLogger('agent_orchestrator').child({ component: 'disposition-service' })
+
+/**
+ * Disposition config carried verbatim from the INVOKE_AGENT node's `onResult`.
+ *
+ * `autoApproveMargin` is optional here (not just defaulted in the zod schema)
+ * because a queue job enqueued before the field existed carries no value —
+ * absent means `0`, which is exactly the historic rule.
+ *
+ * Re-exported from the policy layer, which owns the decision this feeds.
+ */
+
+
+/**
+ * The Invoke Agent node's Review section (spec §7.5), already resolved by the
+ * workflows engine against the run context. Re-exported from the workflows
+ * module so the two sides cannot drift; `workflows` is an OPTIONAL peer, so the
+ * import is type-only and erased at run time.
+ */
+export type AgentDispositionReview =
+  import('@open-mercato/core/modules/workflows/lib/agent-disposition-task').AgentDispositionReview
+
+export type DispositionCtx = {
+  tenantId: string
+  organizationId: string
+  userId?: string
+  workflowInstanceId: string
+  stepId: string
+  /**
+   * Who reviews this proposal and by when, authored on the agent node. Absent
+   * means the unassigned task this service raised before §7.5 — which under the
+   * workflows §6.4 visibility model is a task nobody can act on.
+   */
+  review?: AgentDispositionReview
+}
+
+export type DispositionOutcome =
+  | { kind: 'auto_approved'; proposalId: string; selectedOptionId: string }
+  | { kind: 'user_task'; userTaskId: string; proposalId: string }
+  /** The agent proposed nothing; there is no decision to raise and none to auto-approve. */
+  | { kind: 'none_proposed'; proposalId: string }
+
+export interface DispositionService {
+  dispose(
+    proposal: AgentProposal,
+    onResult: DispositionOnResult,
+    ctx: DispositionCtx,
+  ): Promise<DispositionOutcome>
+}
+
+export type { AutoApprovalDecision, DispositionOnResult }
+export { autoApprovable, evaluateAutoApproval }
+
+/**
+ * MVP DispositionService — a thin DI service called INLINE by the area-02
+ * `INVOKE_AGENT` executor right after `agentRuntime.run`. It does NOT subscribe
+ * to `proposal.created` (an event-driven seam would lose the activity's
+ * transaction scope and race `WAIT_FOR_SIGNAL`).
+ *
+ * - Auto-approve (confidence ≥ threshold, not `alwaysAsk`): dispose through the
+ *   audited `agent_orchestrator.proposals.dispose` Command with the internal
+ *   `auto_approved` verdict (`dispositionBy = 'rule:threshold'`, `skipResume`),
+ *   then return `{ kind:'auto_approved' }`. The Command emits
+ *   `proposal.disposed`. NO `proposal.ready` is emitted and the executor
+ *   proceeds without parking (avoids a park-before-signal race).
+ * - Ask-a-human (below threshold / `alwaysAsk` / null confidence): raise a
+ *   workflows `USER_TASK` surfacing the proposal payload, routed to whoever the
+ *   agent node's Review section names (spec §7.5); the instance stays parked at
+ *   `WAIT_FOR_SIGNAL`. Return `{ kind:'user_task' }`. The operator's dispose
+ *   endpoint later emits `proposal.ready` to resume. Building that row belongs
+ *   to the workflows module — it owns the entity, the audit log and the
+ *   assignment event — so this service passes the Review descriptor to
+ *   `createAgentDispositionTask` rather than assembling the row itself.
+ *
+ * `workflows` is an optional peer: the USER_TASK creation is guarded so the
+ * service degrades gracefully when the module is absent (it still returns a
+ * `user_task` outcome with a synthetic id).
+ */
+export class DispositionServiceImpl implements DispositionService {
+  constructor(private readonly container: AwilixContainer) {}
+
+  async dispose(
+    proposal: AgentProposal,
+    onResult: DispositionOnResult,
+    ctx: DispositionCtx,
+  ): Promise<DispositionOutcome> {
+    const { options } = normalizeProposalEnvelope(proposal.payload, proposal.agentId)
+    // Nothing proposed: terminal at creation, so there is neither a decision to raise
+    // nor a plan to approve. Routed onto the researcher outcome handle downstream.
+    if (options.length === 0) {
+      return { kind: 'none_proposed', proposalId: proposal.id }
+    }
+    const decision = evaluateAutoApproval({
+      options,
+      onResult,
+      ...(await this.resolvePolicyEvidence(proposal)),
+    })
+    if (decision.kind === 'approve') {
+      return this.autoApprove(proposal, decision.option)
+    }
+    return this.raiseUserTask(proposal, ctx, decision.block)
+  }
+
+  /**
+   * The run-level evidence the policy weighs beside the model's own confidence.
+   *
+   * Every read here is best-effort and fails CLOSED in the direction that matters:
+   * a guardrail table we cannot read reports `guardrailsPassed: false` (an
+   * unreadable safety check is not a passed one), while an unreadable tenant
+   * policy falls back to the conservative default rather than to "allow
+   * everything".
+   */
+  private async resolvePolicyEvidence(proposal: AgentProposal): Promise<{
+    guardrailsPassed: boolean
+    traceComplete: boolean
+    tenantPolicy: TenantAutoApprovalPolicy
+  }> {
+    const em = (this.container.resolve('em') as EntityManager).fork()
+    const scope = { tenantId: proposal.tenantId, organizationId: proposal.organizationId }
+
+    let guardrailsPassed = false
+    let traceComplete = false
+    try {
+      const [blocked, spanCount] = await Promise.all([
+        em.count(AgentGuardrailCheck, { ...scope, agentRunId: proposal.runId, result: 'block' }),
+        em.count(AgentSpan, { ...scope, agentRunId: proposal.runId }),
+      ])
+      guardrailsPassed = blocked === 0
+      // A run that left no trace at all cannot be audited after the fact, and an
+      // unauditable mutation is exactly what auto-approval must not produce.
+      traceComplete = spanCount > 0
+    } catch (error) {
+      logger.warn('auto-approval evidence unavailable; holding the proposal for a human', {
+        proposalId: proposal.id,
+        error: error instanceof Error ? error.message : String(error),
+      })
+    }
+
+    return {
+      guardrailsPassed,
+      traceComplete,
+      tenantPolicy: await resolveTenantAutoApprovalPolicy(this.container, proposal.tenantId),
+    }
+  }
+
+  private async autoApprove(
+    proposal: AgentProposal,
+    option: ProposalOption,
+  ): Promise<DispositionOutcome> {
+    const commandBus = this.container.resolve('commandBus') as CommandBus
+    const commandCtx: CommandRuntimeContext = {
+      container: this.container,
+      auth: null,
+      organizationScope: null,
+      selectedOrganizationId: proposal.organizationId,
+      organizationIds: [proposal.organizationId],
+      systemActor: true,
+    }
+    await commandBus.execute<DisposeProposalCommandInput, DisposeProposalCommandResult>(
+      'agent_orchestrator.proposals.dispose',
+      {
+        input: {
+          proposalId: proposal.id,
+          tenantId: proposal.tenantId,
+          organizationId: proposal.organizationId,
+          disposition: 'auto_approved',
+          dispositionBy: 'rule:threshold',
+          selectedOptionId: option.id,
+          skipResume: true,
+        },
+        ctx: commandCtx,
+      },
+    )
+    return { kind: 'auto_approved', proposalId: proposal.id, selectedOptionId: option.id }
+  }
+
+  private async raiseUserTask(
+    proposal: AgentProposal,
+    ctx: DispositionCtx,
+    block: AutoDispositionBlock | null,
+  ): Promise<DispositionOutcome> {
+    if (block) await this.recordAutoDispositionBlock(proposal, block)
+    const userTaskId = await this.createUserTask(proposal, ctx)
+    return { kind: 'user_task', userTaskId, proposalId: proposal.id }
+  }
+
+  /**
+   * A blocked auto-approval is not a failure — it is a proposal that cleared its
+   * threshold and was held anyway, and silence would read as the threshold simply not
+   * being met. Written with a targeted `nativeUpdate` for the same reason
+   * `recordUserTaskId` is: `updated_at` is the proposal's optimistic-lock token and
+   * bumping it here would turn the annotation into a spurious 409 for the operator.
+   */
+  private async recordAutoDispositionBlock(
+    proposal: AgentProposal,
+    block: AutoDispositionBlock,
+  ): Promise<void> {
+    try {
+      const em = (this.container.resolve('em') as EntityManager).fork()
+      await em.nativeUpdate(
+        AgentProposal,
+        { id: proposal.id, tenantId: proposal.tenantId, organizationId: proposal.organizationId },
+        { autoDispositionBlock: block },
+      )
+      proposal.autoDispositionBlock = block
+      await invalidateAgentProposalCache(
+        this.container as Parameters<typeof invalidateAgentProposalCache>[0],
+        { id: proposal.id, tenantId: proposal.tenantId, organizationId: proposal.organizationId },
+        'agent_orchestrator.proposals.auto_block',
+      )
+    } catch (error) {
+      logger.warn('auto-disposition block not recorded', {
+        proposalId: proposal.id,
+        block,
+        error: error instanceof Error ? error.message : String(error),
+      })
+    }
+  }
+
+  private async createUserTask(
+    proposal: AgentProposal,
+    ctx: DispositionCtx,
+  ): Promise<string> {
+    try {
+      const dispositionTask = (await import(
+        '@open-mercato/core/modules/workflows/lib/agent-disposition-task'
+      )) as typeof import('@open-mercato/core/modules/workflows/lib/agent-disposition-task')
+      const em = (this.container.resolve('em') as EntityManager).fork()
+
+      const created = await dispositionTask.createAgentDispositionTask(em, this.container, {
+        workflowInstanceId: ctx.workflowInstanceId,
+        stepId: ctx.stepId,
+        proposalId: proposal.id,
+        agentId: proposal.agentId,
+        proposalPayload: proposal.payload,
+        confidence: proposal.confidence ?? null,
+        taskName: `Dispose agent proposal (${proposal.agentId})`,
+        description: 'Review and approve, edit, or reject the agent proposal.',
+        review: ctx.review ?? null,
+        tenantId: ctx.tenantId,
+        organizationId: ctx.organizationId,
+        userId: ctx.userId,
+      })
+      await this.recordUserTaskId(proposal, created.userTaskId)
+      return created.userTaskId
+    } catch (error) {
+      logger.warn('USER_TASK not created (workflows peer absent?)', {
+        proposalId: proposal.id,
+        workflowInstanceId: ctx.workflowInstanceId,
+        error: error instanceof Error ? error.message : String(error),
+      })
+      return `pending:${proposal.id}`
+    }
+  }
+
+  /**
+   * Link the proposal to the review task raised for it, so `commands/dispose.ts`
+   * can close that task once a verdict lands (A7).
+   *
+   * A targeted `nativeUpdate` rather than a managed write: it must NOT touch
+   * `updated_at`, which is the proposal's optimistic-lock token — bumping it
+   * here would invalidate a caseload modal that had already loaded the row and
+   * turn the link into a spurious 409 for the operator.
+   */
+  private async recordUserTaskId(proposal: AgentProposal, userTaskId: string): Promise<void> {
+    try {
+      const em = (this.container.resolve('em') as EntityManager).fork()
+      await em.nativeUpdate(
+        AgentProposal,
+        { id: proposal.id, tenantId: proposal.tenantId, organizationId: proposal.organizationId },
+        { userTaskId },
+      )
+      proposal.userTaskId = userTaskId
+      await invalidateAgentProposalCache(
+        this.container as Parameters<typeof invalidateAgentProposalCache>[0],
+        { id: proposal.id, tenantId: proposal.tenantId, organizationId: proposal.organizationId },
+        'agent_orchestrator.proposals.review_task',
+      )
+    } catch (error) {
+      // The task exists and the proposal is pending; losing the link costs the
+      // automatic close, never the review itself.
+      logger.warn('proposal not linked to its review task', {
+        proposalId: proposal.id,
+        userTaskId,
+        error: error instanceof Error ? error.message : String(error),
+      })
+    }
+  }
+}

package/src/modules/agent_orchestrator/lib/disposition/resume.ts

@@ -0,0 +1,81 @@
+import type { AwilixContainer } from 'awilix'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { emitAgentOrchestratorEvent } from '../../events'
+import type { AgentProposalDisposition } from '../../data/entities'
+
+const logger = createLogger('agent_orchestrator').child({ component: 'disposition-resume' })
+
+export type ResumeWorkflowForProposalInput = {
+  proposalId: string
+  workflowInstanceId: string
+  stepId: string | null
+  disposition: AgentProposalDisposition
+  proposalPayload?: unknown
+  tenantId: string
+  organizationId: string
+  userId?: string | null
+}
+
+/**
+ * Human-path resume seam (area 03 → area 02).
+ *
+ * Emits the `agent_orchestrator.proposal.ready { workflowInstanceId, stepId, proposalId }`
+ * audit/broadcast event, then delivers the resume signal to the parked workflow
+ * instance via the workflows module's `sendSignal`. Area 02's `WAIT_FOR_SIGNAL`
+ * keys on `signalName = 'agent_orchestrator.proposal.ready'` and matches the
+ * parked instance by `workflowInstanceId`; the merged `disposition`/`payload` lands in
+ * `WorkflowInstance.context` so the downstream effector reads the approved
+ * (possibly edited) payload. A `rejected` proposal resumes too — the workflow
+ * definition's effector transition condition (`disposition ∈ {auto_approved,
+ * approved, edited}`) skips the effector.
+ *
+ * The auto-approve path NEVER reaches here (the executor proceeded inline and
+ * never parked). `proposal.ready` is therefore the human-path resume signal only.
+ *
+ * `workflows` is an optional peer: the resume is best-effort and degrades
+ * gracefully (logs) when the module is absent, so the disposition itself is
+ * already committed and audited regardless of signal delivery.
+ */
+export async function resumeWorkflowForProposal(
+  container: AwilixContainer,
+  em: EntityManager,
+  input: ResumeWorkflowForProposalInput,
+): Promise<void> {
+  await emitAgentOrchestratorEvent(
+    'agent_orchestrator.proposal.ready',
+    {
+      workflowInstanceId: input.workflowInstanceId,
+      stepId: input.stepId,
+      proposalId: input.proposalId,
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+    },
+    { persistent: true },
+  )
+
+  try {
+    const signalHandler = (await import(
+      '@open-mercato/core/modules/workflows/lib/signal-handler'
+    )) as typeof import('@open-mercato/core/modules/workflows/lib/signal-handler')
+    await signalHandler.sendSignal(em, container, {
+      instanceId: input.workflowInstanceId,
+      signalName: 'agent_orchestrator.proposal.ready',
+      payload: {
+        proposalId: input.proposalId,
+        stepId: input.stepId,
+        disposition: input.disposition,
+        proposalPayload: input.proposalPayload,
+      },
+      userId: input.userId ?? undefined,
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+    })
+  } catch (error) {
+    logger.warn('proposal.ready resume signal not delivered', {
+      workflowInstanceId: input.workflowInstanceId,
+      proposalId: input.proposalId,
+      error: error instanceof Error ? error.message : String(error),
+    })
+  }
+}

package/src/modules/agent_orchestrator/lib/disposition/tenantAutoApprovalPolicy.ts

@@ -0,0 +1,100 @@
+import type { AwilixContainer } from 'awilix'
+import { z } from 'zod'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import {
+  ACTION_RISK_TIERS,
+  DEFAULT_TENANT_AUTO_APPROVAL_POLICY,
+  type TenantAutoApprovalPolicy,
+} from './autoApprovalPolicy'
+
+const logger = createLogger('agent_orchestrator').child({ component: 'tenant-auto-approval-policy' })
+
+export const AUTO_APPROVAL_CONFIG_MODULE = 'agent_orchestrator'
+export const AUTO_APPROVAL_CONFIG_NAME = 'auto_approval_policy'
+
+export const tenantAutoApprovalPolicySchema = z.object({
+  enabled: z.boolean(),
+  maxAutoApproveRisk: z.enum(ACTION_RISK_TIERS),
+})
+
+type ModuleConfigServiceLike = {
+  getRecord(
+    moduleId: string,
+    name: string,
+    scope?: { tenantId?: string | null },
+  ): Promise<{ value: unknown } | null>
+}
+
+function resolveModuleConfig(container: AwilixContainer): ModuleConfigServiceLike | null {
+  try {
+    return container.resolve('moduleConfigService') as ModuleConfigServiceLike
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The tenant's standing decision about what may happen without a human.
+ *
+ * A tenant that has configured nothing gets
+ * `DEFAULT_TENANT_AUTO_APPROVAL_POLICY` — enabled, ceiling `medium` — which is
+ * the historic behaviour for every action nobody has declared risky, and refuses
+ * unattended `high`-risk actions. Reading an unset policy as "allow everything"
+ * would make the ceiling opt-in, i.e. absent exactly where it matters.
+ *
+ * A malformed or unreadable record falls back to that default rather than
+ * failing the disposition: losing per-tenant tuning is recoverable, losing the
+ * ability to dispose a proposal is not. It is never read as a LOOSER policy than
+ * the default — the schema only accepts a complete object, so a partially
+ * corrupted record cannot raise the ceiling by omission.
+ */
+export async function resolveTenantAutoApprovalPolicy(
+  container: AwilixContainer,
+  tenantId: string | null,
+): Promise<TenantAutoApprovalPolicy> {
+  return (await readTenantAutoApprovalPolicy(container, tenantId)).policy
+}
+
+/**
+ * Where the effective policy came from — `'tenant'` when this tenant actually
+ * saved one, `'default'` when it is inheriting.
+ *
+ * The disposition path does not care (a policy is a policy), but the settings
+ * screen does: an admin looking at `enabled: true / medium` has to be able to
+ * tell "we decided this" from "nobody has decided anything yet", and every
+ * fallback arm below — no store, no record, a malformed record, an unreadable
+ * one — is honestly `'default'`.
+ */
+export type TenantAutoApprovalPolicySource = 'tenant' | 'default'
+
+export async function readTenantAutoApprovalPolicy(
+  container: AwilixContainer,
+  tenantId: string | null,
+): Promise<{ policy: TenantAutoApprovalPolicy; source: TenantAutoApprovalPolicySource }> {
+  const fallback = {
+    policy: DEFAULT_TENANT_AUTO_APPROVAL_POLICY,
+    source: 'default' as const,
+  }
+  const service = resolveModuleConfig(container)
+  if (!service) return fallback
+  try {
+    const record = await service.getRecord(AUTO_APPROVAL_CONFIG_MODULE, AUTO_APPROVAL_CONFIG_NAME, {
+      tenantId,
+    })
+    if (!record) return fallback
+    const parsed = tenantAutoApprovalPolicySchema.safeParse(record.value)
+    if (!parsed.success) {
+      logger.warn('stored auto-approval policy is malformed; using the conservative default', {
+        tenantId,
+      })
+      return fallback
+    }
+    return { policy: parsed.data, source: 'tenant' }
+  } catch (error) {
+    logger.warn('auto-approval policy unreadable; using the conservative default', {
+      tenantId,
+      error: error instanceof Error ? error.message : String(error),
+    })
+    return fallback
+  }
+}

package/src/modules/agent_orchestrator/lib/eval/assertionResolution.ts

@@ -0,0 +1,105 @@
+import type { AgentEvalAssertion } from '../../data/entities'
+import { evalCaseAssertionRefSchema } from '../../data/validators'
+import { parseScorerConfig, resolveScorerKey } from './registry'
+
+/**
+ * Per-case override of a suite-level assertion. References are by `assertionId`,
+ * NOT by key: `agent_eval_assertions_key_uq` is unique per (org, appliesTo, key),
+ * so a `'*'` row and an agent-specific row routinely share a slug and a key-based
+ * reference would be ambiguous.
+ */
+export type EvalCaseAssertionRef = {
+  assertionId: string
+  /** Shallow-merged over the stored config, then RE-VALIDATED against the scorer. */
+  configOverride?: Record<string, unknown> | null
+  /** Opt out of an inherited assertion for this case only. */
+  disabled?: boolean
+}
+
+export type ResolvedAssertion = {
+  assertion: AgentEvalAssertion
+  scorerKey: string
+  /** Stored config with any case-level override merged in. */
+  config: unknown
+  /** Set when the merged config failed validation — the caller records a skip. */
+  configError?: string[]
+}
+
+/**
+ * Parses the stored `AgentEvalCase.assertions` column through the SAME zod schema
+ * the write path uses, so there is one definition of the shape rather than two
+ * that can drift. Malformed entries are dropped rather than failing the case: the
+ * column predates validation, so a legacy row must still be replayable.
+ */
+export function parseCaseAssertionRefs(raw: unknown): EvalCaseAssertionRef[] {
+  if (!Array.isArray(raw)) return []
+  return raw.flatMap((entry) => {
+    const parsed = evalCaseAssertionRefSchema.safeParse(entry)
+    if (!parsed.success) return []
+    return [
+      {
+        assertionId: parsed.data.assertionId,
+        configOverride: parsed.data.configOverride ?? null,
+        disabled: parsed.data.disabled === true,
+      },
+    ]
+  })
+}
+
+/**
+ * Effective assertion set for one case.
+ *
+ * Precedence: an agent-specific assertion SHADOWS a `'*'` assertion sharing the
+ * same `key` slug — a tenant tightening one agent's rule should not end up running
+ * both the general and the specific version. Case-level refs then apply on top:
+ * `disabled` removes, `configOverride` merges.
+ *
+ * The merged config is re-validated. Without that, a case-level override would
+ * reintroduce exactly the malformed-config-silently-tolerated failure the typed
+ * registry exists to eliminate.
+ */
+export function resolveEffectiveAssertions(
+  assertions: ReadonlyArray<AgentEvalAssertion>,
+  refs: ReadonlyArray<EvalCaseAssertionRef>,
+): ResolvedAssertion[] {
+  const bySlug = new Map<string, AgentEvalAssertion>()
+  for (const assertion of assertions) {
+    const current = bySlug.get(assertion.key)
+    if (!current) {
+      bySlug.set(assertion.key, assertion)
+      continue
+    }
+    // Agent-specific wins over the '*' wildcard — EXCEPT it may not weaken the
+    // gate tier. A tenant-wide `gate` assertion being silently replaced by an
+    // agent-scoped `warn` one sharing its slug would drop a gate with no error,
+    // and the seeded defaults ship exactly such a `'*'` gate (`output_present`).
+    const incomingIsSpecific = assertion.appliesTo !== '*'
+    const currentIsSpecific = current.appliesTo !== '*'
+    const wouldWeakenGate = current.severity === 'gate' && assertion.severity !== 'gate'
+    if (incomingIsSpecific && !currentIsSpecific && !wouldWeakenGate) bySlug.set(assertion.key, assertion)
+  }
+
+  const refsById = new Map(refs.map((ref) => [ref.assertionId, ref]))
+  const resolved: ResolvedAssertion[] = []
+
+  for (const assertion of bySlug.values()) {
+    const ref = refsById.get(assertion.id)
+    if (ref?.disabled) continue
+
+    const scorerKey = resolveScorerKey(assertion)
+    const stored = (assertion.config as Record<string, unknown> | null) ?? {}
+    const config = ref?.configOverride ? { ...stored, ...ref.configOverride } : stored
+
+    if (ref?.configOverride) {
+      const parsed = parseScorerConfig(scorerKey, config)
+      if (!parsed.ok) {
+        resolved.push({ assertion, scorerKey, config, configError: parsed.issues })
+        continue
+      }
+    }
+
+    resolved.push({ assertion, scorerKey, config })
+  }
+
+  return resolved
+}

package/src/modules/agent_orchestrator/lib/eval/canonicalInputKey.ts

@@ -0,0 +1,32 @@
+import { createHash } from 'node:crypto'
+
+/**
+ * Recursively canonicalizes a JSON-ish value so that two structurally-equal
+ * inputs serialize identically regardless of object key order. Arrays keep their
+ * order (order is semantically meaningful); object keys are sorted; primitives
+ * pass through. Non-finite numbers / undefined collapse to null (matching
+ * JSON.stringify semantics) so the result is always a stable string.
+ */
+function canonicalize(value: unknown): unknown {
+  if (value === null || typeof value !== 'object') return value
+  if (Array.isArray(value)) return value.map(canonicalize)
+  const record = value as Record<string, unknown>
+  const sorted: Record<string, unknown> = {}
+  for (const key of Object.keys(record).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))) {
+    const canonicalChild = canonicalize(record[key])
+    if (canonicalChild !== undefined) sorted[key] = canonicalChild
+  }
+  return sorted
+}
+
+/**
+ * Deterministic content hash of an agent run input, stable across object key
+ * order. Used to match a live/playground run's input to an approved golden eval
+ * case (`agent_eval_cases.input_key`). Computed over the DECRYPTED plaintext
+ * input at write time; the resulting hex digest is stored plaintext and is
+ * SQL-queryable. 64-char SHA-256 hex → fits `varchar(64)`.
+ */
+export function canonicalInputKey(input: unknown): string {
+  const canonical = JSON.stringify(canonicalize(input) ?? null)
+  return createHash('sha256').update(canonical).digest('hex')
+}