llm-switcher 1.6.8 → 1.6.10

package/tests/formats.test.mjs

@@ -12,7 +12,7 @@ import {
   createChatStream, buildChatMessage, chatFinish, anthropicStopReason,
   smartText, smartReasoning, sanitizeJsonSchema, normalizeUpstream, buildVertexMessage,
   createCodeAssistStream,
-  budgetToEffort, effortToBudget, normalizeEffort, capEffort, mapEquivalentEffort, EFFORT_LEVELS
+  budgetToEffort, effortToBudget, normalizeEffort, capEffort, mapEquivalentEffort, EFFORT_LEVELS, parseArgs, buildAnthropicMessage
 } from '../formats.mjs';
 import { assertValidAnthropicEvents } from './helpers.mjs';
 
@@ -420,7 +420,7 @@ test('toGeminiSchema: bare string shorthands become Schema objects (Vertex 400 f
   assert.deepEqual(toGeminiSchema('string'), { type: 'string' });
   assert.deepEqual(
     toGeminiSchema({ type: 'object', properties: { tags: { type: 'array', items: 'object' }, n: 'string' } }),
-    { type: 'object', properties: { tags: { type: 'array', items: { type: 'object', properties: {} } }, n: { type: 'string' } } }
+    { type: 'object', properties: { tags: { type: 'array', items: { type: 'object', properties: { _placeholder: { type: 'boolean', description: 'Unused. Leave unset.' } } } }, n: { type: 'string' } } }
   );
 });
 
@@ -1053,3 +1053,293 @@ test('thinkingEffort profile option overrides client effort across all upstreams
   const autoChat = emitUpstreamBody('openai-chat', clientIR, 'gpt-5', { thinkingEffort: 'auto' });
   assert.equal(autoChat.reasoning_effort, 'low');
 });
+
+test('compaction_trigger with tool history keeps tools and forces tool_choice none', () => {
+  const ir = responsesToIR({
+    model: 'm', tools: [fn('Read')], text: { format: { type: 'json_object' } }, input: [
+      { role: 'user', content: 'read it' },
+      { type: 'function_call', call_id: 'c1', name: 'Read', arguments: '{"p":"a"}' },
+      { type: 'function_call_output', call_id: 'c1', output: 'data' },
+      { type: 'compaction_trigger' }
+    ]
+  });
+  assert.equal(ir.toolChoice, 'none');
+  assert.equal(ir.responseFormat, null);
+  const chat = irToChatBody(ir, 'gpt-x');
+  assert.equal(chat.tools?.length, 1);
+  assert.equal(chat.tool_choice, 'none');
+  assert.equal(chat.response_format, undefined);
+  const anthropic = irToAnthropicBody(ir, 'claude-x');
+  assert.equal(anthropic.tools?.length, 1);
+  assert.deepEqual(anthropic.tool_choice, { type: 'none' });
+  assert.ok(anthropic.messages.some(m => m.content.some(b => b.type === 'tool_use')));
+  const vertex = irToVertexBody(ir, 'gemini-x');
+  assert.equal(vertex.tools?.[0].functionDeclarations.length, 1);
+  assert.equal(vertex.toolConfig.functionCallingConfig.mode, 'NONE');
+  // With no tools at all there is nothing to switch off: tool_choice without tools is refused.
+  const bare = responsesToIR({ model: 'm', input: [{ role: 'user', content: 'hi' }, { type: 'compaction_trigger' }] });
+  assert.equal(irToChatBody(bare, 'gpt-x').tool_choice, undefined);
+  assert.equal(irToAnthropicBody(bare, 'claude-x').tool_choice, undefined);
+});
+
+test('anthropic emitters sanitize foreign tool ids consistently', () => {
+  const foreign = 'functions.Read:0';
+  const valid = /^[a-zA-Z0-9_-]+$/;
+  const history = [
+    { role: 'user', content: 'go' },
+    { role: 'assistant', content: [{ type: 'tool_use', id: foreign, name: 'Read', input: {} }] },
+    { role: 'user', content: [{ type: 'tool_result', tool_use_id: foreign, content: 'ok' }] }
+  ];
+  const ir = anthropicToIR({ model: 'x', tools: [{ name: 'Read', input_schema: { type: 'object', properties: {} } }], messages: history });
+  const body = irToAnthropicBody(ir, 'claude-x');
+  const use = body.messages[1].content.find(b => b.type === 'tool_use');
+  assert.match(use.id, valid);
+  assert.equal(body.messages[2].content[0].tool_use_id, use.id);
+  assert.equal(irToAnthropicBody(ir, 'claude-x').messages[1].content[0].id, use.id, 'a replayed history maps identically');
+
+  const message = buildAnthropicMessage({ model: 'x', tools: [{ id: foreign, name: 'Read', args: '{}' }], finish: 'tool_calls' });
+  assert.equal(message.content[0].id, use.id);
+  const events = [];
+  const stream = createAnthropicStream((e, d) => events.push(d), 'x');
+  stream.start();
+  stream.tool({ index: 0, id: foreign, name: 'Read', args: '{}' });
+  stream.finish('tool_calls');
+  assert.equal(events.find(e => e.type === 'content_block_start').content_block.id, use.id);
+
+  const healed = healAnthropicPayload({ model: 'claude', messages: history });
+  assert.equal(healed.changed, true);
+  assert.equal(healed.payload.messages[1].content[0].id, use.id);
+  assert.equal(healed.payload.messages[2].content[0].tool_use_id, use.id);
+
+  // Two ids that differ only in an invalid character must not collide, and a valid id is kept.
+  const ids = ['a.b', 'a:b', 'a_b'].map(id => buildAnthropicMessage({ model: 'x', tools: [{ id, name: 'f', args: '{}' }] }).content[0].id);
+  assert.equal(new Set(ids).size, 3);
+  assert.equal(ids[2], 'a_b');
+  assert.match(buildAnthropicMessage({ model: 'x', tools: [{ id: '', name: 'f', args: '{}' }] }).content[0].id, valid);
+});
+
+test('healAnthropicPayload drops empty system and empty text blocks', () => {
+  const nonEmpty = msgs => msgs.every(m => typeof m.content === 'string' ? m.content.trim()
+    : m.content.length && m.content.every(b => b.type !== 'text' || b.text.trim()));
+  const alternates = msgs => msgs[0].role === 'user' && msgs.every((m, i) => !i || m.role !== msgs[i - 1].role);
+  const r = healAnthropicPayload({
+    model: 'claude', system: [{ type: 'text', text: '' }], messages: [
+      { role: 'user', content: [{ type: 'text', text: '' }, { type: 'text', text: 'hi' }] },
+      { role: 'assistant', content: [{ type: 'text', text: ' ' }, { type: 'tool_use', id: 't1', name: 'f', input: {} }] },
+      { role: 'user', content: [{ type: 'tool_result', tool_use_id: 't1', content: 'ok' }] },
+      { role: 'assistant', content: [{ type: 'text', text: '' }] },
+      { role: 'user', content: [{ type: 'text', text: 'next' }] }
+    ]
+  });
+  assert.equal(r.changed, true);
+  assert.equal('system' in r.payload, false);
+  assert.ok(nonEmpty(r.payload.messages), JSON.stringify(r.payload.messages));
+  assert.ok(alternates(r.payload.messages), JSON.stringify(r.payload.messages));
+  assert.deepEqual(r.payload.messages.at(-1).content.map(b => b.type), ['tool_result', 'text']);
+
+  // A user turn that empties out between two assistant turns, or at the end, keeps its place.
+  const r2 = healAnthropicPayload({
+    model: 'claude', system: [{ type: 'text', text: 'sys' }, { type: 'text', text: '' }], messages: [
+      { role: 'user', content: 'go' },
+      { role: 'assistant', content: 'a' },
+      { role: 'user', content: [{ type: 'text', text: '' }] },
+      { role: 'assistant', content: 'b' },
+      { role: 'user', content: '' }
+    ]
+  });
+  assert.deepEqual(r2.payload.system, [{ type: 'text', text: 'sys' }]);
+  assert.ok(nonEmpty(r2.payload.messages), JSON.stringify(r2.payload.messages));
+  assert.ok(alternates(r2.payload.messages), JSON.stringify(r2.payload.messages));
+  assert.equal(r2.payload.messages.length, 5);
+  assert.equal(r2.payload.messages.at(-1).role, 'user');
+});
+
+test("parseArgs('') returns {}", () => {
+  assert.deepEqual(parseArgs(''), {});
+  assert.deepEqual(parseArgs('  \n'), {});
+  assert.deepEqual(parseArgs('{"a":1}'), { a: 1 });
+});
+
+test('Gemini MALFORMED_FUNCTION_CALL finish is an error, not stop', () => {
+  const ev = normalizeUpstream({ candidates: [{ content: { parts: [] }, finishReason: 'MALFORMED_FUNCTION_CALL' }] }, 'vertex');
+  assert.equal(ev.finish, null);
+  assert.match(String(ev.error), /MALFORMED_FUNCTION_CALL/);
+  const chat = normalizeUpstream({ choices: [{ delta: {}, finish_reason: 'malformed_function_call' }] }, 'openai-chat');
+  assert.match(String(chat.error), /malformed_function_call/i);
+});
+
+// DeepSeek/Kimi thinking mode refuse a tool step whose earlier tool-call turn lost its reasoning_content.
+test('irToChatBody replays thinking as reasoning_content on tool-call turns', () => {
+  const ir = anthropicToIR({ model: 'x', max_tokens: 8000, thinking: { type: 'enabled', budget_tokens: 4000 }, messages: [
+    { role: 'user', content: 'list files' },
+    { role: 'assistant', content: [{ type: 'thinking', thinking: 'I should run ls', signature: 'sig' }, { type: 'tool_use', id: 'toolu_1', name: 'Bash', input: { command: 'ls' } }] },
+    { role: 'user', content: [{ type: 'tool_result', tool_use_id: 'toolu_1', content: 'a.txt' }] },
+    { role: 'assistant', content: [{ type: 'tool_use', id: 'toolu_2', name: 'Bash', input: { command: 'pwd' } }] },
+    { role: 'user', content: [{ type: 'tool_result', tool_use_id: 'toolu_2', content: '/' }] }
+  ] });
+  for (const opts of [{ thinkingMode: 'auto' }, { thinkingMode: 'native', replayReasoning: true }]) {
+    const calls = irToChatBody(ir, 'deepseek-reasoner', opts).messages.filter(m => m.tool_calls);
+    assert.equal(calls[0].reasoning_content, 'I should run ls', opts.thinkingMode);
+    assert.equal(calls[1].reasoning_content, '', opts.thinkingMode);
+  }
+  const off = emitUpstreamBody('openai-chat', ir, 'deepseek-reasoner', { thinkingMode: 'off' });
+  assert.ok(off.messages.every(m => !('reasoning_content' in m)));
+
+  const rir = responsesToIR({ model: 'x', reasoning: { effort: 'high' }, input: [
+    { type: 'message', role: 'user', content: 'go' },
+    { type: 'reasoning', summary: [{ type: 'summary_text', text: 'Plan: run ls' }], encrypted_content: 'opaque' },
+    { type: 'function_call', call_id: 'c1', name: 'shell', arguments: '{}' },
+    { type: 'function_call_output', call_id: 'c1', output: 'ok' }
+  ] });
+  const rb = irToChatBody(rir, 'kimi-k2-thinking', { thinkingMode: 'native', replayReasoning: true });
+  assert.equal(rb.messages.find(m => m.tool_calls).reasoning_content, 'Plan: run ls');
+});
+
+// Strict OpenAI-compatible servers may refuse the extra key, so native mode sends it only on the profile opt-in.
+test('irToChatBody native mode sends no reasoning_content without the profile opt-in', () => {
+  const ir = anthropicToIR({ model: 'x', max_tokens: 8000, thinking: { type: 'enabled', budget_tokens: 4000 }, messages: [
+    { role: 'user', content: 'list files' },
+    { role: 'assistant', content: [{ type: 'thinking', thinking: 'I should run ls', signature: 'sig' }, { type: 'tool_use', id: 'toolu_1', name: 'Bash', input: { command: 'ls' } }] },
+    { role: 'user', content: [{ type: 'tool_result', tool_use_id: 'toolu_1', content: 'a.txt' }] },
+    { role: 'assistant', content: [{ type: 'tool_use', id: 'toolu_2', name: 'Bash', input: { command: 'pwd' } }] },
+    { role: 'user', content: [{ type: 'tool_result', tool_use_id: 'toolu_2', content: '/' }] }
+  ] });
+  const cases = [
+    ['gpt-5', ir, { thinkingMode: 'native' }],
+    ['deepseek-reasoner', ir, { thinkingMode: 'native' }],
+    ['gpt-5', ir, { thinkingMode: 'native', replayReasoning: 'yes' }],
+    ['gpt-5', { ...ir, replayReasoning: true }, { thinkingMode: 'native' }]
+  ];
+  for (const [model, input, opts] of cases) {
+    const body = irToChatBody(input, model, opts);
+    assert.ok(body.messages.some(m => m.tool_calls), 'fixture has tool-call turns');
+    assert.ok(body.messages.every(m => !('reasoning_content' in m)), `${model} ${JSON.stringify(opts)}`);
+  }
+});
+
+test('irToAnthropicBody drops thinking for an unsigned tool loop', () => {
+  const ir = responsesToIR({ model: 'x', reasoning: { effort: 'high' }, input: [
+    { type: 'message', role: 'user', content: 'run ls' },
+    { type: 'function_call', call_id: 'c1', name: 'shell', arguments: '{"command":["ls"]}' },
+    { type: 'function_call_output', call_id: 'c1', output: 'a.txt' }
+  ] });
+  const body = irToAnthropicBody(ir, 'claude-opus-4-6');
+  assert.equal(body.thinking, undefined);
+  assert.equal(body.messages.at(-1).content[0].type, 'tool_result');
+  const forced = irToAnthropicBody(ir, 'claude-opus-4-6', { thinkingEffort: 'high' });
+  assert.equal(forced.thinking, undefined);
+  const fresh = irToAnthropicBody(responsesToIR({ model: 'x', reasoning: { effort: 'high' }, input: 'hi' }), 'claude-opus-4-6');
+  assert.equal(fresh.thinking?.type, 'enabled');
+});
+
+test('toGeminiSchema never emits an empty nested OBJECT', () => {
+  const out = toGeminiSchema({ type: 'object', properties: {
+    env: { type: 'object', additionalProperties: { type: 'string' } },
+    list: { type: 'array', items: { type: 'object' } },
+    either: { anyOf: [{ type: 'object' }, { type: 'string' }] },
+    short: 'object'
+  } });
+  const walk = (s, nested) => {
+    if (!s || typeof s !== 'object') return;
+    if (nested && s.type === 'object') assert.ok(Object.keys(s.properties || {}).length, JSON.stringify(s));
+    for (const p of Object.values(s.properties || {})) walk(p, true);
+    if (s.items) walk(s.items, true);
+    for (const b of s.anyOf || []) walk(b, true);
+  };
+  walk(out, false);
+  assert.deepEqual(toGeminiSchema({ type: 'object' }), { type: 'object', properties: {} });
+});
+
+test('irToVertexBody wraps tool output with $ keys', () => {
+  const output = JSON.stringify({ $ref: '#/definitions/Pet', definitions: { Pet: { $id: 'p' } } });
+  const nested = JSON.stringify({ a: { b: [{ $schema: 'x' }] } });
+  const ir = { ...anthropicToIR({ model: 'x', messages: [
+    { role: 'user', content: 'go' },
+    { role: 'assistant', content: [{ type: 'tool_use', id: 't1', name: 'Bash', input: {} }, { type: 'tool_use', id: 't2', name: 'Bash', input: {} }, { type: 'tool_use', id: 't3', name: 'Bash', input: {} }] },
+    { role: 'user', content: [
+      { type: 'tool_result', tool_use_id: 't1', content: output },
+      { type: 'tool_result', tool_use_id: 't2', content: nested },
+      { type: 'tool_result', tool_use_id: 't3', content: '{"ok":true}' }
+    ] }
+  ] }) };
+  const responses = irToVertexBody(ir, 'gemini-2.5-pro').contents.flatMap(c => c.parts).filter(p => p.functionResponse).map(p => p.functionResponse.response);
+  assert.deepEqual(responses[0], { result: output });
+  assert.deepEqual(responses[1], { result: nested });
+  assert.deepEqual(responses[2], { ok: true });
+});
+
+test('toGeminiSchema stringifies an untyped const', () => {
+  const out = toGeminiSchema({ type: 'object', properties: { flag: { const: true }, n: { const: 3 }, s: { const: 'x' } } });
+  assert.deepEqual(out.properties.flag, { enum: ['true'], type: 'string' });
+  assert.deepEqual(out.properties.n, { enum: ['3'], type: 'string' });
+  assert.deepEqual(out.properties.s, { enum: ['x'], type: 'string' });
+});
+
+test('responsesToIR keeps long colliding tool names distinct', () => {
+  const ns = `mcp__${'server_with_a_long_name_'.repeat(3)}`;
+  const ir = responsesToIR({ model: 'x', input: [
+    { type: 'message', role: 'user', content: 'go' },
+    { type: 'function_call', call_id: 'c1', namespace: ns, name: 'list_items_with_filter_b', arguments: '{}' },
+    { type: 'function_call_output', call_id: 'c1', output: 'ok' }
+  ], tools: [{ type: 'namespace', name: ns, tools: [
+    { type: 'function', name: 'list_items_with_filter_a', parameters: { type: 'object', properties: {} } },
+    { type: 'function', name: 'list_items_with_filter_b', parameters: { type: 'object', properties: {} } }
+  ] }] });
+  const names = ir.tools.map(t => t.name);
+  assert.equal(names.length, 2);
+  assert.notEqual(names[0], names[1]);
+  assert.ok(names.every(n => n.length <= 64 && /^[A-Za-z0-9_-]+$/.test(n)), names.join());
+  assert.equal(ir.toolMeta[names[1]].name, 'list_items_with_filter_b');
+  assert.equal(ir.messages[1].toolCalls[0].name, names[1]);
+  assert.equal(responsesToIR({ model: 'x', input: 'hi', tools: [{ type: 'function', name: 'read_file', parameters: {} }] }).tools[0].name, 'read_file');
+});
+
+test('sanitizeJsonSchema drops null keywords and lookaround patterns', () => {
+  const out = sanitizeJsonSchema({ type: 'object', required: null, description: null, properties: {
+    slug: { type: 'string', pattern: '^(?!-)[a-z-]+$' },
+    tag: { type: 'string', pattern: '(?<=#)\\w+' },
+    plain: { type: 'string', pattern: '^[a-z]+$', default: null },
+    named: { type: 'string', pattern: '^(?<year>\\d{4})$' },
+    pattern: { type: 'string', enum: ['a', null], const: null }
+  } });
+  assert.equal('required' in out, false);
+  assert.equal('description' in out, false);
+  assert.equal('pattern' in out.properties.slug, false);
+  assert.equal('pattern' in out.properties.tag, false);
+  assert.equal(out.properties.plain.pattern, '^[a-z]+$');
+  assert.equal(out.properties.plain.default, null);
+  assert.equal(out.properties.named.pattern, '^(?<year>\\d{4})$');
+  assert.deepEqual(out.properties.pattern, { type: 'string', enum: ['a', null], const: null });
+  assert.deepEqual(sanitizeJsonSchema({ type: 'object', properties: {}, default: { a: null, b: {} } }).default, { a: null, b: {} });
+});
+
+test('irToVertexBody never ends on a model turn', () => {
+  const ir = anthropicToIR({ model: 'x', messages: [
+    { role: 'user', content: 'Write a haiku' },
+    { role: 'assistant', content: 'Autumn moon' }
+  ] });
+  const body = irToVertexBody(ir, 'gemini-2.5-pro');
+  assert.equal(body.contents.at(-1).role, 'user');
+  assert.ok(body.contents.some(c => c.role === 'model' && c.parts.some(p => p.text === 'Autumn moon')), 'the prefill text is kept');
+});
+
+test('healAnthropicPayload dedupes repeated tool_use ids', () => {
+  const use = (id, cmd) => ({ type: 'tool_use', id, name: 'Bash', input: { command: cmd } });
+  const result = (id, text) => ({ type: 'tool_result', tool_use_id: id, content: text });
+  const r = healAnthropicPayload({ model: 'claude', messages: [
+    { role: 'user', content: 'go' },
+    { role: 'assistant', content: [use('functions_Bash_0', 'ls')] },
+    { role: 'user', content: [result('functions_Bash_0', 'a.txt')] },
+    { role: 'assistant', content: [use('functions_Bash_0', 'pwd'), use('functions_Bash_1', 'id')] },
+    { role: 'user', content: [result('functions_Bash_0', '/'), result('functions_Bash_1', 'uid')] }
+  ] });
+  assert.equal(r.changed, true);
+  const msgs = r.payload.messages;
+  const ids = msgs.filter(m => m.role === 'assistant').flatMap(m => m.content.filter(b => b.type === 'tool_use').map(b => b.id));
+  assert.equal(new Set(ids).size, ids.length, ids.join());
+  assert.ok(ids.every(id => /^[a-zA-Z0-9_-]+$/.test(id)));
+  assert.equal(ids[0], 'functions_Bash_0');
+  // Each result still answers its own call.
+  assert.deepEqual(msgs[2].content.map(b => [b.tool_use_id, b.content]), [[ids[0], 'a.txt']]);
+  assert.deepEqual(msgs[4].content.map(b => [b.tool_use_id, b.content]), [[ids[1], '/'], [ids[2], 'uid']]);
+});

package/tests/gateway.e2e.test.mjs

@@ -112,6 +112,10 @@ function startUpstream() {
           res.writeHead(429, { 'Content-Type': 'application/json', 'retry-after': '7' });
           return res.end(JSON.stringify({ error: { message: 'slow down' } }));
         }
+        if (lastUser.includes('CONTEXT_OVERFLOW')) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          return res.end(JSON.stringify({ error: { message: "This model's maximum context length is 131072 tokens. However, you requested 140000 tokens (132000 in the messages, 8000 in the completion). Please reduce the length of the messages or completion.", type: 'invalid_request_error', code: 'invalid_request_error' } }));
+        }
         if (lastUser.includes('APPLY_PATCH')) {
           return sse(res, [
             { choices: [{ index: 0, delta: { tool_calls: [{ index: 0, id: 'call_patch', type: 'function', function: { name: 'apply_patch', arguments: '{"input":"*** Begin Patch\\n' } }] } }] },
@@ -407,7 +411,7 @@ test('Codex via ag/* target: Gemini-hostile tool schemas are rewritten before up
   const params = up.body.tools[0].function.parameters;
   assert.deepEqual(params.properties.ids, { type: 'array', items: { type: 'string' }, nullable: true });
   assert.deepEqual(params.properties.part, { type: 'object', properties: { t: { type: 'string' } } });
-  assert.deepEqual(params.properties.raw, { type: 'object', properties: {} });
+  assert.deepEqual(params.properties.raw, { type: 'object', properties: { _placeholder: { type: 'boolean', description: 'Unused. Leave unset.' } } });
   assert.deepEqual(params.required, ['ids']);
   assert.ok(!JSON.stringify(params).includes('$ref'), 'no $ref survives');
   assert.equal(params.$defs, undefined);
@@ -594,6 +598,20 @@ test('Upstream 429 is returned in Anthropic error shape with retry-after', async
   assert.deepEqual(json, { type: 'error', error: { type: 'rate_limit_error', message: 'slow down' } });
 });
 
+// Claude Code compacts only on "prompt is too long", and Codex only on context_length_exceeded.
+test('sendClientError maps context overflow per client', async () => {
+  const cc = await post('/v1/messages', { model: 'claude-opus-4-6', max_tokens: 10, messages: [{ role: 'user', content: 'CONTEXT_OVERFLOW' }] });
+  assert.equal(cc.status, 400);
+  const ccJson = await cc.json();
+  assert.equal(ccJson.error.type, 'invalid_request_error');
+  assert.match(ccJson.error.message, /^prompt is too long: 140000 tokens > 131072 maximum/);
+  const codex = await post('/v1/responses', { model: 'gpt-5-codex', input: 'CONTEXT_OVERFLOW' });
+  assert.equal(codex.status, 400);
+  const codexJson = await codex.json();
+  assert.equal(codexJson.error.code, 'context_length_exceeded');
+  assert.match(codexJson.error.message, /maximum context length is 131072/);
+});
+
 test('Mid-stream upstream error surfaces as an error event instead of a fake end_turn', async () => {
   const res = await post('/v1/messages', { model: 'claude-opus-4-6', max_tokens: 10, stream: true, messages: [{ role: 'user', content: 'MID_STREAM_ERROR' }] });
   const events = parseSSE(await res.text());

package/tests/ui.test.mjs

@@ -124,10 +124,11 @@ test('documentation tab is properly integrated with sidebar navigation, sections
   // Table of Contents navigation exists
   assert.match(html, /<nav class="docs-toc" id="docsToc"/);
   
-  // All 10 core sections exist
+  // All 11 core sections exist
   const expectedSections = [
     'doc-overview',
     'doc-install',
+    'doc-intact',
     'doc-cli',
     'doc-blindfold',
     'doc-agy',
@@ -150,3 +151,8 @@ test('documentation tab is properly integrated with sidebar navigation, sections
   assert.match(html, /function copyDocCode\(/);
   assert.match(html, /function initDocsScrollSpy\(/);
 });
+
+test('sidebar menu is arranged logically by frequency of use', () => {
+  const navMatches = [...html.matchAll(/data-nav="([^"]+)"/g)].map(m => m[1]);
+  assert.deepEqual(navMatches, ['routes', 'logs', 'models', 'doctor', 'goal-check', 'compact', 'docs']);
+});