Files
gods-eye-view/src/voice/integrationContract.test.mjs
T
Manjunath 207373389a fix(voice): resolve areas per view, without accents and per natural place
From review:
- An answer the view picked ("Springfield" over Illinois) is reused or
  shared only within the same ~2° view cell, so asking again elsewhere no
  longer gets the first state's area.
- Admin names compare with accents folded on Latin letters only: "Quebec"
  matches "Québec" and "Cordoba" asks between Argentina and Spain, while a
  Thai or Devanagari mark still tells names apart.
- A Natural Earth name used by several features is one place with every
  part when they touch (the Great Rift Valley, the Lau Group across 180°)
  and a question when they are far apart (Flores); natural places can now
  be candidates.
- The AREAS rule and the area tool descriptions are tighter, leaving a
  ~270-character margin under the 55,500 prompt ceiling, and resolve_area
  no longer names osm_query when that tool is not offered.
2026-11-03 19:36:25 +05:30

727 lines
25 KiB
JavaScript

// Cross-feature voice contracts, driven through the real action runner:
// one result contract (engine fields → model payload → voice card), shared
// pointing for imagery, result-set ownership between OSM and the analyst,
// imagery panel ownership, conversation lifetime, and progress narration.
//
// Run with: npm test
import test from 'node:test';
import assert from 'node:assert/strict';
import { createTestVoiceUi } from '../testSupport/voiceUi.mjs';
import { buildPointerSnapshot } from './pointerContext.js';
import {
initialVoiceCardState,
reduceVoiceCard,
voiceCardView,
} from './voiceCardPresentation.js';
import { createNarrationScheduler } from './narration.js';
import { createVoiceCommands } from './sessionCommands.js';
import { candidate } from '../layers/recentImagery/testDoubles.mjs';
import { harness, tick } from './voiceWorkflowHarness.mjs';
import { realtimeInstructions } from '../../server/providers/openai/instructions.js';
import {
GEV_REALTIME_TOOLS,
realtimeTools,
} from '../../server/providers/openai/tools.js';
import { attachVoiceResult } from './speech.js';
/** Run one call and fold it through the real voice card. */
async function throughCard(runner, name, args, card = initialVoiceCardState()) {
const callId = `call-${name}-${Math.random()}`;
let state = reduceVoiceCard(card, { type: 'interruption' });
state = reduceVoiceCard(state, {
type: 'action-call',
name,
callId,
arguments: args,
});
const result = await runner(name, args);
state = reduceVoiceCard(state, {
type: 'action-result',
name,
callId,
result,
});
const shown = voiceCardView(state);
return { result, view: shown.result, steps: shown.steps };
}
// ── 1. One result contract ────────────────────────────────────────────────
test('an analyst count reaches the model and the card with its scope and caveats', async () => {
const { runner } = harness();
const { result, view } = await throughCard(runner, 'analyst_query', {
layers: ['flights'],
scope: { kind: 'anywhere' },
});
assert.equal(result.ok, true);
assert.equal(result.complete, true, 'complete survives the projection');
assert.equal(result.say, '3 aircraft anywhere in the loaded data.');
assert.equal(view.visible, true, 'the card shows an analyst result');
assert.equal(view.title, '3 aircraft anywhere in the loaded data');
assert.ok(
!view.lines.includes('anywhere in the loaded data'),
'the scope is in the title, not repeated as a line',
);
assert.deepEqual(
view.referents.map((r) => r.label),
['UAL1', 'DAL2', 'SWA3'],
);
});
test('long analyst scope text is bounded identically for speech and card', () => {
const result = attachVoiceResult('analyst_query', {
ok: true,
action: 'analyst_query',
count: 12,
complete: true,
scopeLabel:
'over the extraordinarily long alpine administrative research corridor with a deliberately verbose official name',
coverage: { layersQueried: [{ layerKey: 'flights' }] },
});
const started = reduceVoiceCard(initialVoiceCardState(), {
type: 'action-call',
name: 'analyst_query',
callId: 'long-scope',
arguments: {},
});
const card = reduceVoiceCard(started, {
type: 'action-result',
name: 'analyst_query',
callId: 'long-scope',
result,
});
const title = voiceCardView(card).result.title;
assert.equal(result.say, title);
assert.ok(title.length <= 64);
assert.match(title, /…$/);
});
test('a capped count is a floor everywhere: model, card and caveat', async () => {
const rows = Array.from({ length: 250_001 }, (_, i) => ({
id: `F${i}`,
lat: 10,
lon: 20,
}));
const flights = {
getStats: () => ({ count: 400_000, lastUpdate: Date.now() }),
getAnalystRecords: (max) => rows.slice(0, max),
};
const { runner } = harness({ flights });
const { result, view } = await throughCard(runner, 'analyst_query', {
layers: ['flights'],
scope: { kind: 'anywhere' },
limit: 1,
});
assert.equal(result.complete, false);
assert.match(result.say, /^At least 250,000 aircraft/);
assert.match(view.title, /^At least 250,000 aircraft/);
assert.ok(
view.notes.some((note) => /counted 250,000 of 400,000/.test(note)),
'the cap is on screen',
);
});
test('a partial answer names the layers it could not read', async () => {
const { runner } = harness();
const { result, view } = await throughCard(runner, 'analyst_query', {
layers: ['flights', 'earthquakes'],
scope: { kind: 'anywhere' },
});
assert.equal(result.partial, true);
assert.match(result.say, /Partial; earthquakes not answered/);
assert.deepEqual(result.unanswered, ['earthquakes']);
assert.ok(view.chips.includes('partial'));
// The card names the layer; the result keeps its key for the model.
assert.ok(view.notes.includes('Not answered: Earthquakes (24h)'));
});
test('combined Contacts aircraft use one semantic noun on the model and card surfaces', async () => {
const { runner } = harness();
const { result, view } = await throughCard(runner, 'analyst_query', {
layers: ['flights', 'military'],
scope: { kind: 'anywhere' },
});
assert.match(result.say, / aircraft /);
assert.doesNotMatch(result.say, / results /);
assert.ok(
result.say.startsWith(`${view.title}.`),
'speech starts with the exact card headline before its partial-status sentence',
);
});
test('an ambiguous region keeps its candidates through the runner and asks on the card', async () => {
const { runner } = harness();
const area = await throughCard(runner, 'resolve_area', {
query: 'Punjab',
draw: true,
});
assert.equal(area.result.needsClarification, true);
assert.equal(area.result.candidates.length, 2);
assert.equal(area.view.title, 'Which Punjab?');
assert.equal(
area.steps.at(-1).status,
'done',
'a question is not a failed step',
);
assert.deepEqual(area.view.lines, [
'1 · Punjab — state or province, India',
'2 · Punjab — state or province, Pakistan',
]);
const count = await throughCard(runner, 'analyst_query', {
layers: ['flights'],
scope: { kind: 'region', name: 'Punjab' },
});
assert.equal(count.result.ok, false);
assert.equal(
count.result.needsClarification,
true,
'the refusal projection keeps the clarification',
);
assert.equal(count.result.candidates.length, 2);
assert.equal(count.view.title, 'Which Punjab?');
});
test('an area count carries its areaId; an approximate outline says so on the card', async () => {
const { runner } = harness();
const kathmandu = await throughCard(runner, 'resolve_area', {
query: 'Kathmandu',
});
assert.equal(kathmandu.view.title, 'Kathmandu');
assert.ok(kathmandu.view.notes.includes('Source: OpenStreetMap'));
const inside = await runner('analyst_query', {
layers: ['flights'],
scope: { kind: 'area', areaId: kathmandu.result.areaId },
});
assert.equal(inside.areaId, kathmandu.result.areaId);
const around = await throughCard(runner, 'resolve_area', {
query: 'Ferry Building',
around: true,
});
assert.equal(around.result.approximate, true);
assert.ok(around.view.chips.includes('approximate'));
assert.ok(around.view.lines.includes('250 m around the landmark'));
});
test('imagery shows the chosen day, the catalog window and its cap on the card', async () => {
const h = harness();
const pending = throughCard(h.runner, 'find_imagery', {});
await tick();
h.imagery.catalog.searches.at(-1).resolve({
candidates: [
candidate('S30', '2026-09-18', 3),
candidate('L30', '2026-09-10', 60),
],
truncated: true,
errors: [],
});
const { result, view } = await pending;
assert.equal(result.ok, true);
assert.equal(view.title, 'Sentinel-2 · 2026-09-18');
assert.ok(view.lines.includes('The catalog covers the last 30 days'));
assert.ok(
view.notes.some((note) => /Catalog truncated/.test(note)),
'a capped catalog is not presented as complete',
);
});
test('OSM places render as a card with numbered referents', async () => {
const { runner } = harness();
const { result, view } = await throughCard(runner, 'osm_query', {
what: 'hospitals',
});
assert.equal(result.ok, true);
assert.equal(view.title, '3 hospitals');
assert.deepEqual(
view.referents.map((r) => [r.n, r.label]),
[
[1, 'Bir Hospital'],
[2, 'Military Hospital'],
[3, 'unnamed hospital'],
],
);
assert.ok(view.notes.includes('Source: OpenStreetMap'));
});
test('"the second one" is the second row the card lists', async () => {
const { runner, referents } = harness();
await runner('analyst_query', {
layers: ['flights'],
scope: { kind: 'anywhere' },
});
assert.equal(referents.get(2).label, 'DAL2');
assert.equal(referents.get(-1).label, 'SWA3');
});
test('numbered and last referents are exactly the five rows the card displays', async () => {
const flights = {
getStats: () => ({ count: 6, lastUpdate: Date.now() }),
getAnalystRecords: () =>
Array.from({ length: 6 }, (_, index) => ({
id: `F${index + 1}`,
icao24: `f${index + 1}`,
callsign: `CALL${index + 1}`,
lat: 30,
lon: -97,
})),
};
const { runner, referents } = harness({ flights });
const { view } = await throughCard(runner, 'analyst_query', {
layers: ['flights'],
scope: { kind: 'anywhere' },
limit: 6,
});
assert.deepEqual(
view.referents.map((entry) => entry.label),
['CALL1', 'CALL2', 'CALL3', 'CALL4', 'CALL5'],
);
assert.equal(referents.get(6), null);
assert.equal(referents.get(-1)?.label, 'CALL5');
});
test('a follow-up naming other layers than the last answer is refused, not answered from it', async () => {
const { runner } = harness();
await runner('analyst_query', {
layers: ['flights'],
scope: { kind: 'anywhere' },
});
const mismatch = await runner('analyst_query', {
layers: ['earthquakes'],
followUp: true,
});
assert.equal(mismatch.ok, false);
assert.equal(mismatch.code, 'FOLLOW_UP_MISMATCH');
assert.match(mismatch.error, /flights, not earthquakes/);
});
// ── 2. Imagery pointing uses the turn snapshot ────────────────────────────
const groundAt = (lat, lon) =>
buildPointerSnapshot({
at: 'keydown',
x: 100,
y: 100,
width: 800,
height: 600,
pick: { ground: { lat, lon } },
});
test('imagery of "this spot" searches the turn snapshot, not the cursor now', async () => {
const h = harness({ pointer: groundAt(10, 20) });
const pending = h.runner('find_imagery', { area: 'pointer' });
await tick();
const box = h.imagery.layer.getSnapshot().box;
assert.ok(
Math.abs((box.west + box.east) / 2 - 20) < 0.01 &&
Math.abs((box.south + box.north) / 2 - 10) < 0.01,
`box centred on the snapshot (${JSON.stringify(box)})`,
);
h.imagery.catalog.resolveLast([candidate('S30', '2026-09-18', 3)]);
const result = await pending;
assert.equal(result.ok, true);
assert.deepEqual(result.resolvedFrom, { source: 'pointer', label: null });
});
test('imagery with no fresh pointer asks, and never searches the view instead', async () => {
const h = harness({ pointer: null });
const result = await h.runner('find_imagery', { area: 'pointer' });
assert.equal(result.ok, false);
assert.match(result.error, /Nothing is under the pointer/);
assert.equal(h.imagery.catalog.searches.length, 0);
h.setPointer({ fresh: false, at: 'keydown' });
const stale = await h.runner('find_imagery', { area: 'pointer' });
assert.equal(stale.ok, false, 'a stale snapshot is not "here"');
});
// ── 3. Result-set ownership ───────────────────────────────────────────────
test('after a place search, "those" and "the second one" mean the places', async () => {
const { runner, referents } = harness();
await runner('analyst_query', {
layers: ['flights'],
scope: { kind: 'anywhere' },
});
assert.equal(referents.get(2).label, 'DAL2');
await runner('osm_query', { what: 'hospitals' });
assert.equal(
referents.get(2).label,
'Military Hospital',
'the place list replaced the aircraft list',
);
const followUp = await runner('analyst_query', {
layers: ['osm-places'],
followUp: true,
filters: [{ field: 'name', op: 'contains', value: 'Bir' }],
});
assert.equal(followUp.ok, true);
assert.deepEqual(
followUp.items.map((item) => item.name),
['Bir Hospital'],
'the follow-up filtered the hospitals, not the old aircraft',
);
const fresh = await runner('analyst_query', {
layers: ['osm-places'],
scope: { kind: 'anywhere' },
});
assert.equal(fresh.count, 3, 'a fresh osm-places query reads the layer');
});
test('an empty place search clears the numbered list instead of keeping older rows', async () => {
const h = harness({ osmHits: [] });
await h.runner('analyst_query', {
layers: ['flights'],
scope: { kind: 'anywhere' },
});
assert.ok(h.referents.get(1));
const none = await h.runner('osm_query', { what: 'hospitals' });
assert.equal(none.count, 0);
assert.equal(h.referents.get(1), null);
});
// ── 4. Imagery panel ownership ────────────────────────────────────────────
test('an operator pin chosen while the catalog loads is never overwritten', async () => {
const h = harness();
const { layer, catalog } = h.imagery;
const pending = h.runner('find_imagery', {});
await tick();
const theirs = candidate('S30', '2026-09-19', 40);
let taken = false;
layer.subscribe((snap) => {
if (taken || snap.searching || !snap.candidates.length) return;
taken = true;
layer.setAssignment('a', theirs.key); // same box, operator's pin
});
catalog.resolveLast([candidate('S30', '2026-09-20', 2), theirs]);
const result = await pending;
assert.equal(result.ok, false);
assert.equal(result.code, 'DISPLACED');
assert.equal(layer.getSnapshot().pins.a.key, theirs.key, 'their pin stays');
});
test('a source or mode change by hand during the search also hands the panel back', async () => {
for (const change of [
(layer) => layer.setSources({ hls: true, viirs: true }),
(layer) => layer.setMode('ab'),
]) {
const h = harness();
const pending = h.runner('find_imagery', {});
await tick();
change(h.imagery.layer);
h.imagery.catalog.resolveLast([candidate('S30', '2026-09-20', 2)]);
const result = await pending;
assert.equal(result.code, 'DISPLACED');
assert.equal(h.imagery.layer.getSnapshot().pins.a.key, null);
}
});
// ── 5. Conversation lifetime ──────────────────────────────────────────────
test('a runner reset aborts its owned imagery search and a retry succeeds', async () => {
const h = harness();
const pending = h.runner('find_imagery', {});
await tick();
const firstSearch = h.imagery.catalog.searches.at(-1);
assert.equal(firstSearch.request.signal.aborted, false);
h.runner.resetConversation();
const cancelled = await pending;
assert.equal(firstSearch.request.signal.aborted, true);
assert.equal(cancelled.code, 'CANCELLED');
assert.equal(h.imagery.layer.getSnapshot().pins.a.key, null);
const retry = h.runner('find_imagery', {});
await tick();
h.imagery.catalog.resolveLast([candidate('S30', '2026-09-20', 2)]);
const recovered = await retry;
assert.equal(recovered.ok, true);
assert.equal(h.imagery.layer.getSnapshot().pins.a.key, 'S30:2026-09-20');
});
test('runner disposal aborts its owned OSM provider work without a late commit', async () => {
let providerSignal;
let resolveProvider;
const h = harness({
osmSearch: (_request, { signal }) => {
providerSignal = signal;
return new Promise((resolve) => {
resolveProvider = resolve;
});
},
});
const pending = h.runner('osm_query', { what: 'hospitals' });
await tick();
assert.equal(providerSignal.aborted, false);
h.runner.dispose();
assert.equal(providerSignal.aborted, true);
resolveProvider({
ok: true,
mode: 'features',
features: [
{ id: 'node/late', lat: 27.7, lon: 85.31, tags: { name: 'Late' } },
],
truncated: false,
});
const cancelled = await pending;
assert.equal(cancelled.code, 'CANCELLED');
assert.equal(h.referents.get(1), null);
});
test('a mic restart keeps area handles', async () => {
const h = harness();
const area = await h.runner('resolve_area', { query: 'Kathmandu' });
// A place search in flight when the session ends must not seed the next.
const late = h.runner('osm_query', { what: 'hospitals' });
h.runner.resetConversation();
await late;
const followUp = await h.runner('analyst_query', {
layers: ['osm-places'],
followUp: true,
});
assert.equal(followUp.code, 'NO_RESULT_CONTEXT');
const inside = await h.runner('analyst_query', {
layers: ['flights'],
scope: { kind: 'area', areaId: area.areaId },
});
assert.equal(inside.ok, true, 'the area handle outlives the mic session');
});
test('a mic restart forgets the last answer and in-flight writes', async () => {
const h = harness();
await h.runner('analyst_query', {
layers: ['flights'],
scope: { kind: 'anywhere' },
});
// A query in flight when the session ends must not seed the new session.
const late = h.runner('analyst_query', {
layers: ['flights'],
scope: { kind: 'anywhere' },
});
h.runner.resetConversation();
await late;
const followUp = await h.runner('analyst_query', {
layers: ['flights'],
followUp: true,
});
assert.equal(followUp.code, 'NO_RESULT_CONTEXT');
});
test('the voice controls reset the runner on stop and dispose it on removal', async () => {
const previous = globalThis.window;
globalThis.window = {};
try {
const h = harness();
const ui = createTestVoiceUi();
const lifetime = new AbortController();
let emitState;
const controls = createVoiceCommands({
runner: h.runner,
signal: lifetime.signal,
createControl: () => ui,
createCard: () => null,
createSession({ emit }) {
emitState = (state) => emit({ type: 'state', state });
return {
async start() {
emitState('listening');
},
stop() {
emitState('idle');
},
sendText() {},
sendMapEvent() {},
};
},
});
await controls.session.start();
await h.runner('analyst_query', {
layers: ['flights'],
scope: { kind: 'anywhere' },
});
controls.session.stop();
const after = await h.runner('analyst_query', {
layers: ['flights'],
followUp: true,
});
assert.equal(after.code, 'NO_RESULT_CONTEXT', 'stop cleared the memory');
lifetime.abort();
const removed = await h.runner('analyst_query', {
layers: ['flights'],
scope: { kind: 'anywhere' },
});
assert.equal(removed.cancelled, true, 'a disposed runner does nothing');
} finally {
globalThis.window = previous;
}
});
// ── 6. Progress narration through the scheduler ───────────────────────────
function fakeClock() {
let now = 0;
const timers = [];
return {
now: () => now,
setTimer(fn, ms) {
const timer = { fn, at: now + ms, done: false };
timers.push(timer);
return timer;
},
clearTimer(timer) {
if (timer) timer.done = true;
},
advance(ms) {
const until = now + ms;
for (;;) {
const next = timers
.filter((t) => !t.done && t.at <= until)
.sort((a, b) => a.at - b.at)[0];
if (!next) break;
now = next.at;
next.done = true;
next.fn();
}
now = until;
},
};
}
/**
* Start one tool under the real scheduler, let its workflow report its
* phases, and read what the scheduler says once the first line is due (the
* tool is still counted as running, as a slow call would be).
*/
async function narrated(name, args, whileRunning = async () => {}, on) {
const clock = fakeClock();
const spoken = [];
const scheduler = createNarrationScheduler({
speak: (line) => spoken.push(line),
now: clock.now,
setTimer: clock.setTimer,
clearTimer: clock.clearTimer,
});
const h = harness(on ? { on } : {});
scheduler.userTurnEnded();
scheduler.toolStarted('c1', { name, label: 'x' });
const pending = h.runner(name, args, {
progress: (update) => scheduler.progress('c1', update),
});
await tick();
await whileRunning(h);
await pending;
clock.advance(1600);
scheduler.toolFinished('c1');
return spoken;
}
test('a slow annotate_map call narrates its real phase', async () => {
assert.deepEqual(
await narrated('annotate_map', {
annotations: [{ type: 'pin', target: 'Ferry Building' }],
}),
['Finding Ferry Building on the map.'],
);
});
test('slow area, place and imagery calls narrate their real phase', async () => {
assert.deepEqual(await narrated('resolve_area', { query: 'Kathmandu' }), [
'Finding Kathmandu on the map.',
]);
assert.deepEqual(
await narrated('resolve_area', { query: 'Kathmandu', draw: true }),
['Outlining Kathmandu.'],
);
const places = ['flights', 'osm-places'];
assert.deepEqual(
await narrated('osm_query', { what: 'hospitals' }, undefined, places),
['Searching OpenStreetMap for hospitals.'],
);
assert.deepEqual(
await narrated('find_imagery', {}, async (h) => {
await tick();
h.imagery.catalog.resolveLast([candidate('S30', '2026-09-18', 3)]);
}),
['Loading the image.'],
);
});
// ── 7. One statement per policy ───────────────────────────────────────────
test('the cloud prompt states precedence and caveat speech once', () => {
const lines = realtimeInstructions().split('\n');
const starting = (prefix) => lines.filter((line) => line.startsWith(prefix));
assert.equal(starting('WHERE,').length, 1, 'one precedence rule');
const where = starting('WHERE,')[0];
const order = [
'a place the user names',
'explicit pointing',
'Contacts subject',
'the current view',
];
const at = order.map((phrase) => where.indexOf(phrase));
assert.ok(
at.every((i, n) => i >= 0 && (n === 0 || i > at[n - 1])),
'named → pointing → Contacts/selection → view',
);
const tools = JSON.stringify(GEV_REALTIME_TOOLS);
// Caveat speech is one policy: lower bounds and partial answers are spoken.
const caveatRules = lines.filter((line) => /caveat/i.test(line));
assert.equal(caveatRules.length, 1, caveatRules.join('\n'));
assert.match(
caveatRules[0],
/speak a caveat only when it changes the answer/,
);
assert.match(caveatRules[0], /Lower bounds \("at least 500"\)/);
assert.doesNotMatch(tools, /mention display\.caveat/);
assert.doesNotMatch(
realtimeInstructions(),
/"approximately"\/"roughly" for a tool number/,
);
});
test('boundaries route to resolve_area; annotate_map is for marks', () => {
const lines = realtimeInstructions().split('\n');
const areas = lines.filter((line) => line.startsWith('AREAS:'));
assert.equal(areas.length, 1);
assert.match(areas[0], /annotate_map is for marks, not boundaries/);
const whiteboard = lines.find((line) => line.startsWith('WHITEBOARD'));
assert.doesNotMatch(whiteboard, /boundar/);
assert.doesNotMatch(
GEV_REALTIME_TOOLS.find((tool) => tool.name === 'annotate_map').description,
/boundar/,
);
});
test('without an operator Overpass the prompt never offers place search', () => {
const plain = realtimeInstructions();
assert.doesNotMatch(plain, /osm_query/);
assert.doesNotMatch(
JSON.stringify(realtimeTools()),
/osm_query/,
'no other tool description points at it either',
);
assert.equal(
realtimeTools().some((tool) => tool.name === 'osm_query'),
false,
);
assert.match(
realtimeInstructions(undefined, { overpass: true }),
/osm_query/,
);
assert.ok(
realtimeTools({ overpass: true }).some((t) => t.name === 'osm_query'),
);
});
test('the Realtime prompt stays within its size budget', () => {
// Instructions plus tool schemas, in characters, under the same 55,500
// ceiling as the deixis prompt lint. Voice geometry adds resolve_area,
// find_imagery and the analyst area scopes (osm_query only with an
// operator Overpass).
const size = (overpass) =>
realtimeInstructions(undefined, { overpass }).length +
JSON.stringify(realtimeTools({ overpass })).length;
assert.ok(size(false) <= 55_500, `default prompt ${size(false)} chars`);
assert.ok(size(true) <= 55_500, `with Overpass ${size(true)} chars`);
});