fix(ai): harden Jev fallback and Crossfire signals

Author: Programcode

docs/architecture.md

@@ -58,7 +58,7 @@ Client-side environment selection is a developer convenience, not authorization.
 
 [`supabase/functions/ai/index.ts`](../supabase/functions/ai/index.ts) serves non-streaming structured tools and practice modes. [`supabase/functions/ai-stream/index.ts`](../supabase/functions/ai-stream/index.ts) serves Ask over server-sent events.
 
-For a validated Crossfire next turn, the server may ask Jev to classify only the newest completed question-answer exchange. The optional directness, concession, and follow-up signal is attached by turn ID to the answer; a missing or failed Jev decision never invalidates the main Crossfire reply. Draft version 1 remains compatible because turn signals are optional.
+For a validated Crossfire next turn, the server returns the reply first with a short-lived signed sidecar token. The client then requests a Jev classification of only the newest completed question-answer exchange, without reserving a second daily quota unit. The optional directness, concession, and follow-up signal is attached by turn ID to the answer; a missing, slow, forged, or failed sidecar never delays or invalidates the main reply. Draft version 1 remains compatible because turn signals are optional.
 
 A configured mock provider bypasses Supabase for local and test behavior. It is not authenticated backend evidence.
 

e2e/crossfire.spec.ts

@@ -4,8 +4,10 @@ import { setLocale, stubSupabaseSession } from './helpers/auth';
 type CrossfireRequest = {
   feature: string;
   input: {
-    operation: 'next-turn' | 'debrief';
+    operation: 'next-turn' | 'debrief' | 'signal';
     expectedReply?: 'question' | 'answer';
+    reply?: { type: 'question' | 'answer'; text: string };
+    signalToken?: string;
     config: { mode: 'question-ai' | 'ai-questions-user'; useSourceLibrary: boolean };
     transcript: Array<{ id: string; kind: 'question' | 'answer'; text: string }>;
   };
@@ -43,6 +45,21 @@ async function installDeterministicBackend(page: Page, requests: CrossfireReques
     if (url.pathname.endsWith('/functions/v1/ai')) {
       const body = route.request().postDataJSON() as CrossfireRequest;
       requests.push(body);
+      if (body.input.operation === 'signal') {
+        const answerTurnId = body.input.reply?.type === 'answer'
+          ? `T${body.input.transcript.length + 1}`
+          : body.input.transcript.at(-1)?.kind === 'answer' ? body.input.transcript.at(-1)?.id : undefined;
+        const signal = answerTurnId ? {
+          answerTurnId,
+          answerQuality: body.input.reply?.type === 'answer' ? 'direct' : 'partial',
+          answerQualityConfidence: 0.91,
+          concession: body.input.reply?.type === 'answer' ? 'none' : 'implicit',
+          concessionConfidence: 0.76,
+          followUpOpportunity: 0.82,
+        } : undefined;
+        await route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify({ output: signal ? { signal } : {} }) });
+        return;
+      }
       if (body.input.operation === 'next-turn') {
         if (failFirstAnswer && !answerFailed && body.input.expectedReply === 'answer') {
           answerFailed = true;
@@ -60,18 +77,8 @@ async function installDeterministicBackend(page: Page, requests: CrossfireReques
                 ? 'What evidence connects fewer private cars to safer streets?'
                 : 'How would you answer the strongest enforcement objection?',
             };
-        const answerTurnId = body.input.expectedReply === 'answer'
-          ? `T${body.input.transcript.length + 1}`
-          : body.input.transcript.at(-1)?.kind === 'answer' ? body.input.transcript.at(-1)?.id : undefined;
-        const signal = answerTurnId ? {
-          answerTurnId,
-          answerQuality: body.input.expectedReply === 'answer' ? 'direct' : 'partial',
-          answerQualityConfidence: 0.91,
-          concession: body.input.expectedReply === 'answer' ? 'none' : 'implicit',
-          concessionConfidence: 0.76,
-          followUpOpportunity: 0.82,
-        } : undefined;
-        await route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify({ output, ...(signal ? { signal } : {}) }) });
+        const hasCompletedExchange = output.type === 'answer' || body.input.transcript.at(-1)?.kind === 'answer';
+        await route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify({ output, ...(hasCompletedExchange ? { signalToken: 'e2e-signal-token' } : {}) }) });
         return;
       }
 
@@ -151,7 +158,7 @@ test('Let the AI question me alternates roles and completes a debrief', async ({
   await expect(page.getByTestId('crossfire-debrief')).toBeVisible();
   await expect(page.getByText('Partial answer')).toBeVisible();
   expect(requests[0].input).toMatchObject({ operation: 'next-turn', expectedReply: 'question', config: { mode: 'ai-questions-user', useSourceLibrary: false } });
-  expect(requests[1].input.transcript.at(-1)?.text).toBe('Traffic exposure falls when trips shift to transit and walking.');
+  expect(requests.filter((request) => request.input.operation === 'next-turn')[1].input.transcript.at(-1)?.text).toBe('Traffic exposure falls when trips shift to transit and walking.');
   expect(requests.at(-1)?.input.operation).toBe('debrief');
   await page.screenshot({ path: testInfo.outputPath('crossfire-ai-questions-user-final.png'), fullPage: true });
 });

src/lib/ai/client.ts

@@ -39,11 +39,13 @@ import {
   CrossfireAIInputSchema,
   CrossfireDebriefSchema,
   CrossfireReplySchema,
+  CrossfireSignalInputSchema,
   CrossfireTurnSignalSchema,
   collectDebriefTurnIds,
   type CrossfireAIInput,
   type CrossfireDebrief,
   type CrossfireReply,
+  type CrossfireSignalInput,
   type CrossfireTurnSignal,
 } from '@/lib/crossfire/schemas';
 
@@ -739,7 +741,7 @@ export async function crossfire(
   rawInput: CrossfireAIInput,
   config: ProviderConfig,
   options: Pick<AIRequestOptions, 'signal'> = {},
-): Promise<(CrossfireReply & { signal?: CrossfireTurnSignal }) | CrossfireDebrief> {
+): Promise<(CrossfireReply & { signalToken?: string }) | CrossfireDebrief> {
   const input = CrossfireAIInputSchema.safeParse(rawInput);
   if (!input.success) {
     throw new AIResponseError('Crossfire request did not match the expected schema.', {
@@ -757,7 +759,7 @@ export async function crossfire(
       timeoutMs: CROSSFIRE_REQUEST_TIMEOUT_MS,
       signal: options.signal,
       transformResponse: (rawData) => {
-        const data = rawData as { output: unknown; signal?: unknown };
+        const data = rawData as { output: unknown; signalToken?: unknown };
         if (input.data.operation === 'next-turn') {
           const reply = CrossfireReplySchema.safeParse(data.output);
           if (!reply.success || reply.data.type !== input.data.expectedReply) {
@@ -767,27 +769,11 @@ export async function crossfire(
                 : { issues: reply.error.issues },
             });
           }
-          if (data.signal === undefined) return reply.data;
-          const signal = CrossfireTurnSignalSchema.safeParse(data.signal);
-          if (!signal.success) {
-            throw new AIResponseError('Crossfire signal did not match the expected schema.', { details: { issues: signal.error.issues } });
+          if (data.signalToken === undefined) return reply.data;
+          if (typeof data.signalToken !== 'string' || !data.signalToken.trim() || data.signalToken.length > 128) {
+            throw new AIResponseError('Crossfire signal token was invalid.');
           }
-          const answerTurns = [
-            ...input.data.transcript,
-            {
-              id: `T${input.data.transcript.length + 1}`,
-              sequence: input.data.transcript.length + 1,
-              speaker: 'ai' as const,
-              kind: reply.data.type,
-              text: reply.data.text,
-              createdAt: 0,
-            },
-          ];
-          const target = answerTurns.find((turn) => turn.id === signal.data.answerTurnId);
-          if (!target || target.kind !== 'answer') {
-            throw new AIResponseError('Crossfire signal referenced an unknown or non-answer turn.');
-          }
-          return { ...reply.data, signal: signal.data };
+          return { ...reply.data, signalToken: data.signalToken };
         }
 
         const debrief = CrossfireDebriefSchema.safeParse(data.output);
@@ -803,6 +789,41 @@ export async function crossfire(
   );
 }
 
+export async function crossfireSignal(
+  rawInput: CrossfireSignalInput,
+  config: ProviderConfig,
+  options: Pick<AIRequestOptions, 'signal'> = {},
+): Promise<CrossfireTurnSignal | undefined> {
+  const input = CrossfireSignalInputSchema.safeParse(rawInput);
+  if (!input.success) {
+    throw new AIResponseError('Crossfire signal request did not match the expected schema.', { details: { issues: input.error.issues } });
+  }
+  return await callSupabaseAI<CrossfireTurnSignal | undefined>(
+    'crossfire',
+    withOutputLanguage({ operation: 'signal', ...input.data }),
+    config,
+    {
+      includeActiveSources: false,
+      includeCustomSystemPrompt: false,
+      timeoutMs: 5_000,
+      signal: options.signal,
+      transformResponse: (rawData) => {
+        const output = (rawData as { output?: unknown }).output;
+        if (!output || typeof output !== 'object' || Array.isArray(output) || !('signal' in output)) return undefined;
+        const parsed = CrossfireTurnSignalSchema.safeParse((output as { signal: unknown }).signal);
+        if (!parsed.success) throw new AIResponseError('Crossfire signal did not match the expected schema.', { details: { issues: parsed.error.issues } });
+        const turns = [
+          ...input.data.transcript,
+          { id: `T${input.data.transcript.length + 1}`, kind: input.data.reply.type },
+        ];
+        const target = turns.find((turn) => turn.id === parsed.data.answerTurnId);
+        if (!target || target.kind !== 'answer') throw new AIResponseError('Crossfire signal referenced an unknown or non-answer turn.');
+        return parsed.data;
+      },
+    },
+  );
+}
+
 export function mapAIError(
   error: { message: string; context?: unknown },
   requestId: string,

src/lib/crossfire/reducer.ts

@@ -19,6 +19,7 @@ export type CrossfireAction =
   | { type: 'session-started'; sessionId: string; now: number }
   | { type: 'user-turn-submitted'; turn: CrossfireTurn; expectedReply: 'question' | 'answer' }
   | { type: 'ai-turn-received'; turn: CrossfireTurn; signal?: CrossfireTurnSignal }
+  | { type: 'signal-received'; signal: CrossfireTurnSignal }
   | {
     type: 'request-failed';
     expectedReply: 'question' | 'answer';
@@ -67,6 +68,16 @@ function appendTurn(turns: CrossfireTurn[], turn: CrossfireTurn): CrossfireTurn[
   return [...turns, parsed.data];
 }
 
+function attachSignal(turns: CrossfireTurn[], value: CrossfireTurnSignal): CrossfireTurn[] | null {
+  const signal = CrossfireTurnSignalSchema.safeParse(value);
+  if (!signal.success) return null;
+  const targetIndex = turns.findIndex((turn) => turn.id === signal.data.answerTurnId && turn.kind === 'answer');
+  if (targetIndex < 0) return null;
+  const target = CrossfireTurnSchema.safeParse({ ...turns[targetIndex], signal: signal.data });
+  if (!target.success) return null;
+  return turns.map((turn, index) => index === targetIndex ? target.data : turn);
+}
+
 export function crossfireReducer(state: CrossfireState, action: CrossfireAction): CrossfireState {
   switch (action.type) {
     case 'config-patched': {
@@ -111,16 +122,16 @@ export function crossfireReducer(state: CrossfireState, action: CrossfireAction)
       let turns = appendTurn(state.turns, action.turn);
       if (!turns) return state;
       if (action.signal) {
-        const signal = CrossfireTurnSignalSchema.safeParse(action.signal);
-        if (!signal.success) return state;
-        const targetIndex = turns.findIndex((turn) => turn.id === signal.data.answerTurnId && turn.kind === 'answer');
-        if (targetIndex < 0) return state;
-        const target = CrossfireTurnSchema.safeParse({ ...turns[targetIndex], signal: signal.data });
-        if (!target.success) return state;
-        turns = turns.map((turn, index) => index === targetIndex ? target.data : turn);
+        turns = attachSignal(turns, action.signal);
+        if (!turns) return state;
       }
       return { ...state, turns, request: { status: 'idle' } };
     }
+    case 'signal-received': {
+      if (state.phase === 'setup') return state;
+      const turns = attachSignal(state.turns, action.signal);
+      return turns ? { ...state, turns } : state;
+    }
     case 'request-failed': {
       if (state.phase !== 'active' || state.request.status !== 'pending') return state;
       if (action.expectedReply !== state.request.expectedReply) return state;

src/lib/crossfire/schemas.ts

@@ -150,6 +150,14 @@ export const CrossfireAIInputSchema = z.discriminatedUnion('operation', [
 ]);
 export type CrossfireAIInput = z.infer<typeof CrossfireAIInputSchema>;
 
+export const CrossfireSignalInputSchema = z.object({
+  config: CrossfireConfigSchema,
+  transcript: CrossfireTranscriptSchema,
+  reply: CrossfireReplySchema,
+  signalToken: z.string().trim().min(1).max(128),
+}).strict();
+export type CrossfireSignalInput = z.infer<typeof CrossfireSignalInputSchema>;
+
 export const CrossfireRequestStateSchema = z.discriminatedUnion('status', [
   z.object({ status: z.literal('idle') }).strict(),
   z.object({

src/pages/CrossfirePage.tsx

@@ -22,7 +22,7 @@ import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/com
 import { Checkbox } from '@/components/ui/checkbox';
 import { Label } from '@/components/ui/label';
 import { Textarea } from '@/components/ui/textarea';
-import { crossfire, AIResponseError, isTimeoutError } from '@/lib/ai/client';
+import { crossfire, crossfireSignal, AIResponseError, isTimeoutError } from '@/lib/ai/client';
 import { getUserFacingAIError } from '@/lib/ai/error-display';
 import {
   canEndCrossfireSession,
@@ -316,11 +316,23 @@ export default function CrossfirePage() {
         });
         return;
       }
+      const reply = { type: result.type, text: result.text };
       dispatch({
         type: 'ai-turn-received',
         turn: nextTurn(snapshot.turns.length + 1, 'ai', result.type, result.text),
-        signal: result.signal,
       });
+      if (result.signalToken) {
+        void crossfireSignal({
+          config: snapshot.config,
+          transcript: snapshot.turns,
+          reply,
+          signalToken: result.signalToken,
+        }, modelConfig, { signal: controller.signal })
+          .then((signal) => {
+            if (signal && !controller.signal.aborted) dispatch({ type: 'signal-received', signal });
+          })
+          .catch((): void => {});
+      }
     } catch (error) {
       if (controller.signal.aborted) return;
       const classified = classifyError(error);

src/test/ai/crossfire-client.test.ts

@@ -34,7 +34,7 @@ vi.mock('@/lib/stores/session-store', () => ({
 
 vi.mock('@/hooks/use-toast', () => ({ toast: vi.fn() }));
 
-import { AIResponseError, crossfire } from '@/lib/ai/client';
+import { AIResponseError, crossfire, crossfireSignal } from '@/lib/ai/client';
 
 const config: ProviderConfig = {
   provider: 'google',
@@ -150,19 +150,20 @@ describe('Crossfire AI client', () => {
 
   it('parses a valid live signal and rejects unknown or non-answer targets', async () => {
     const signal = { answerTurnId: 'T2', answerQuality: 'direct', answerQualityConfidence: 0.9, concession: 'none', concessionConfidence: 0.8, followUpOpportunity: 0.75 };
-    mocks.invoke.mockResolvedValueOnce({ data: { output: { type: 'answer', text: 'Answer.' }, signal }, error: null });
-    await expect(crossfire(nextTurnInput(), config)).resolves.toEqual({ type: 'answer', text: 'Answer.', signal });
+    mocks.invoke.mockResolvedValueOnce({ data: { output: { type: 'answer', text: 'Answer.' }, signalToken: 'signed-token' }, error: null });
+    await expect(crossfire(nextTurnInput(), config)).resolves.toEqual({ type: 'answer', text: 'Answer.', signalToken: 'signed-token' });
 
-    mocks.invoke.mockResolvedValueOnce({ data: { output: { type: 'answer', text: 'Answer.' }, signal: { ...signal, answerTurnId: 'T99' } }, error: null });
-    await expect(crossfire(nextTurnInput(), config)).rejects.toBeInstanceOf(AIResponseError);
+    const next = nextTurnInput();
+    if (next.operation !== 'next-turn') throw new Error('Unexpected fixture');
+    const signalInput = { config: next.config, transcript: next.transcript, reply: { type: 'answer' as const, text: 'Answer.' }, signalToken: 'signed-token' };
+    mocks.invoke.mockResolvedValueOnce({ data: { output: { signal } }, error: null });
+    await expect(crossfireSignal(signalInput, config)).resolves.toEqual(signal);
+
+    mocks.invoke.mockResolvedValueOnce({ data: { output: { signal: { ...signal, answerTurnId: 'T99' } } }, error: null });
+    await expect(crossfireSignal(signalInput, config)).rejects.toBeInstanceOf(AIResponseError);
 
-    mocks.invoke.mockResolvedValueOnce({ data: { output: { type: 'question', text: 'Next?' }, signal: { ...signal, answerTurnId: 'T1' } }, error: null });
-    const aiQuestionInput = nextTurnInput();
-    if (aiQuestionInput.operation !== 'next-turn') throw new Error('Unexpected fixture');
-    aiQuestionInput.config.mode = 'ai-questions-user';
-    aiQuestionInput.transcript = [];
-    aiQuestionInput.expectedReply = 'question';
-    await expect(crossfire(aiQuestionInput, config)).rejects.toBeInstanceOf(AIResponseError);
+    mocks.invoke.mockResolvedValueOnce({ data: { output: { signal: { ...signal, answerTurnId: 'T1' } } }, error: null });
+    await expect(crossfireSignal(signalInput, config)).rejects.toBeInstanceOf(AIResponseError);
   });
 
   it('validates debrief shape and every transcript reference', async () => {

src/test/crossfire/reducer.test.ts

@@ -74,7 +74,9 @@ describe('crossfireReducer', () => {
     let state = crossfireReducer(configured(), { type: 'session-started', sessionId: 'signal-session', now: 1 });
     state = crossfireReducer(state, { type: 'user-turn-submitted', turn: turn(1, 'user', 'question'), expectedReply: 'answer' });
     const signal = { answerTurnId: 'T2', answerQuality: 'direct' as const, answerQualityConfidence: 0.9, concession: 'none' as const, concessionConfidence: 0.8, followUpOpportunity: 0.75 };
-    state = crossfireReducer(state, { type: 'ai-turn-received', turn: turn(2, 'ai', 'answer'), signal });
+    state = crossfireReducer(state, { type: 'ai-turn-received', turn: turn(2, 'ai', 'answer') });
+    expect(state.phase === 'active' && state.turns[1].signal).toBeUndefined();
+    state = crossfireReducer(state, { type: 'signal-received', signal });
     expect(state.phase === 'active' && state.turns[0].signal).toBeUndefined();
     expect(state.phase === 'active' && state.turns[1].signal).toEqual(signal);
 
@@ -90,7 +92,8 @@ describe('crossfireReducer', () => {
     state = crossfireReducer(state, { type: 'ai-turn-received', turn: turn(1, 'ai', 'question') });
     state = crossfireReducer(state, { type: 'user-turn-submitted', turn: turn(2, 'user', 'answer'), expectedReply: 'question' });
     const signal = { answerTurnId: 'T2', answerQuality: 'partial' as const, answerQualityConfidence: 0.8, concession: 'implicit' as const, concessionConfidence: 0.7, followUpOpportunity: 0.9 };
-    state = crossfireReducer(state, { type: 'ai-turn-received', turn: turn(3, 'ai', 'question'), signal });
+    state = crossfireReducer(state, { type: 'ai-turn-received', turn: turn(3, 'ai', 'question') });
+    state = crossfireReducer(state, { type: 'signal-received', signal });
     expect(state.phase === 'active' && state.turns[1].signal).toEqual(signal);
     expect(state.phase === 'active' && state.turns[2].signal).toBeUndefined();
   });