@flowcodex/core 0.3.0

package/tests/agent-loop.test.ts

@@ -0,0 +1,490 @@
+import { describe, expect, it, vi } from 'vitest';
+import { runAgentLoop } from '../src/agent/agent-loop.js';
+import { AgentContext } from '../src/agent/context.js';
+import { DefaultRetryPolicy } from '../src/infrastructure/retry-policy.js';
+import { EventBus } from '../src/kernel/events.js';
+import type { Context } from '../src/types/context.js';
+import type { LLMEvent, LLMRequest, LLMResponse, Provider } from '../src/types/provider.js';
+
+function mockProvider(events: LLMEvent[]): Provider {
+  const i = 0;
+  return {
+    name: 'mock',
+    async *stream(_req: LLMRequest): AsyncIterable<LLMEvent> {
+      for (const ev of events) {
+        yield ev;
+      }
+    },
+    async complete(req: LLMRequest): Promise<LLMResponse> {
+      throw new Error('not implemented');
+    },
+  };
+}
+
+describe('AgentContext', () => {
+  it('creates with defaults', () => {
+    const ctx = new AgentContext({
+      model: { provider: 'anthropic', model: 'claude-sonnet-4-6' },
+      projectRoot: '/tmp/project',
+    });
+    expect(ctx.model.model).toBe('claude-sonnet-4-6');
+    expect(ctx.workingDir).toBe('/tmp/project');
+    expect(ctx.budget.maxIterations).toBe(50);
+    expect(ctx.messages).toHaveLength(0);
+    expect(ctx.btwNotes).toHaveLength(0);
+    expect(ctx.tools).toHaveLength(0);
+  });
+
+  it('setWorkingDir validates containment', () => {
+    const ctx = new AgentContext({
+      model: { provider: 'anthropic', model: 'test' },
+      projectRoot: '/tmp/project',
+    });
+    ctx.setWorkingDir('src');
+    expect(ctx.workingDir).toContain('src');
+    expect(() => ctx.setWorkingDir('../../etc')).toThrow(/outside project root/);
+  });
+
+  it('registerAbortHook returns unsubscribe', () => {
+    const ctx = new AgentContext({
+      model: { provider: 'anthropic', model: 'test' },
+      projectRoot: '/tmp/project',
+    });
+    const fn = vi.fn();
+    const unsub = ctx.registerAbortHook(fn);
+    expect(ctx.abortHooks ?? fn).toBeTruthy();
+    unsub();
+  });
+
+  it('drainAbortHooks fires in LIFO and swallows errors', async () => {
+    const ctx = new AgentContext({
+      model: { provider: 'anthropic', model: 'test' },
+      projectRoot: '/tmp/project',
+    });
+    const order: string[] = [];
+    ctx.registerAbortHook(() => {
+      order.push('first');
+    });
+    ctx.registerAbortHook(() => {
+      order.push('second');
+    });
+    await ctx.drainAbortHooks();
+    expect(order).toEqual(['second', 'first']);
+  });
+
+  it('defaults readOnly to false', () => {
+    const ctx = new AgentContext({
+      model: { provider: 'anthropic', model: 'test' },
+      projectRoot: '/tmp/project',
+    });
+    expect(ctx.readOnly).toBe(false);
+  });
+
+  it('sets readOnly from init option', () => {
+    const ctx = new AgentContext({
+      model: { provider: 'anthropic', model: 'test' },
+      projectRoot: '/tmp/project',
+      readOnly: true,
+    });
+    expect(ctx.readOnly).toBe(true);
+  });
+});
+
+describe('runAgentLoop', () => {
+  it('completes a text-only response (no tool_use)', async () => {
+    const ctx = new AgentContext({
+      model: { provider: 'mock', model: 'test-model' },
+      projectRoot: '/tmp/project',
+    });
+    ctx.messages.push({ role: 'user', content: [{ type: 'text', text: 'hello' }] });
+
+    const events = new EventBus();
+    const provider = mockProvider([
+      { type: 'text_delta', text: 'Hello, ' },
+      { type: 'text_delta', text: 'world!' },
+      { type: 'finish', usage: { input: 10, output: 5 }, stopReason: 'end_turn' },
+    ]);
+
+    const result = await runAgentLoop({
+      ctx,
+      provider,
+      events,
+      retry: new DefaultRetryPolicy(),
+      signal: new AbortController().signal,
+    });
+
+    expect(result.status).toBe('completed');
+    expect(result.iterations).toBe(1);
+    expect(result.finalText).toBe('Hello, world!');
+    expect(ctx.messages).toHaveLength(2);
+    expect(ctx.messages[1]!.role).toBe('assistant');
+  });
+
+  it('continues on tool_use and then completes', async () => {
+    const ctx = new AgentContext({
+      model: { provider: 'mock', model: 'test-model' },
+      projectRoot: '/tmp/project',
+    });
+    ctx.messages.push({ role: 'user', content: [{ type: 'text', text: 'read file' }] });
+
+    const events = new EventBus();
+    let callCount = 0;
+    const provider: Provider = {
+      name: 'mock',
+      async *stream(_req: LLMRequest): AsyncIterable<LLMEvent> {
+        callCount++;
+        if (callCount === 1) {
+          yield { type: 'tool_use_start', id: 'toolu_1', name: 'read' };
+          yield { type: 'tool_use_input_delta', id: 'toolu_1', partialJson: '{"path":"file.txt"}' };
+          yield { type: 'tool_use_stop', id: 'toolu_1' };
+          yield { type: 'finish', usage: { input: 10, output: 5 }, stopReason: 'tool_use' };
+        } else {
+          yield { type: 'text_delta', text: 'Done reading.' };
+          yield { type: 'finish', usage: { input: 20, output: 3 }, stopReason: 'end_turn' };
+        }
+      },
+      async complete(): Promise<LLMResponse> {
+        throw new Error('not implemented');
+      },
+    };
+
+    let toolExecuted = false;
+    const result = await runAgentLoop({
+      ctx,
+      provider,
+      events,
+      retry: new DefaultRetryPolicy(),
+      signal: new AbortController().signal,
+      executeTools: async (toolUses) => {
+        toolExecuted = true;
+        ctx.messages.push({
+          role: 'user',
+          content: [
+            {
+              type: 'tool_result',
+              tool_use_id: toolUses[0]!.id,
+              content: 'file contents here',
+            },
+          ],
+        });
+      },
+    });
+
+    expect(result.status).toBe('completed');
+    expect(result.iterations).toBe(2);
+    expect(toolExecuted).toBe(true);
+    expect(result.finalText).toBe('Done reading.');
+  });
+
+  it('aborts cleanly on signal abort', async () => {
+    const ctx = new AgentContext({
+      model: { provider: 'mock', model: 'test' },
+      projectRoot: '/tmp/project',
+    });
+    const ctrl = new AbortController();
+    ctrl.abort();
+
+    const result = await runAgentLoop({
+      ctx,
+      provider: mockProvider([]),
+      events: new EventBus(),
+      retry: new DefaultRetryPolicy(),
+      signal: ctrl.signal,
+    });
+
+    expect(result.status).toBe('aborted');
+  });
+
+  it('hits iteration limit', async () => {
+    const ctx = new AgentContext({
+      model: { provider: 'mock', model: 'test' },
+      projectRoot: '/tmp/project',
+      budget: { maxIterations: 1, maxTokens: 1000, maxCost: 10 },
+    });
+    ctx.messages.push({ role: 'user', content: [{ type: 'text', text: 'hi' }] });
+
+    const events = new EventBus();
+    const provider: Provider = {
+      name: 'mock',
+      async *stream(): AsyncIterable<LLMEvent> {
+        yield { type: 'tool_use_start', id: 't1', name: 'loop' };
+        yield { type: 'tool_use_input_delta', id: 't1', partialJson: '{}' };
+        yield { type: 'tool_use_stop', id: 't1' };
+        yield { type: 'finish', usage: { input: 1, output: 1 }, stopReason: 'tool_use' };
+      },
+      async complete(): Promise<LLMResponse> {
+        throw new Error('not impl');
+      },
+    };
+
+    const result = await runAgentLoop({
+      ctx,
+      provider,
+      events,
+      retry: new DefaultRetryPolicy(),
+      signal: new AbortController().signal,
+      maxIterations: 1,
+      executeTools: async () => {
+        ctx.messages.push({
+          role: 'user',
+          content: [{ type: 'tool_result', tool_use_id: 't1', content: 'ok' }],
+        });
+      },
+    });
+
+    expect(result.status).toBe('limit_reached');
+  });
+
+  it('filters mutating tools when ctx.readOnly is true', async () => {
+    const ctx = new AgentContext({
+      model: { provider: 'mock', model: 'test' },
+      projectRoot: '/tmp/project',
+      readOnly: true,
+    });
+    ctx.messages.push({ role: 'user', content: [{ type: 'text', text: 'hi' }] });
+
+    ctx.tools = [
+      { name: 'read', mutating: false },
+      { name: 'grep', mutating: false },
+      { name: 'write', mutating: true },
+      { name: 'bash', mutating: true },
+    ];
+
+    let capturedRequest: LLMRequest | undefined;
+    const provider: Provider = {
+      name: 'mock',
+      async *stream(req: LLMRequest): AsyncIterable<LLMEvent> {
+        capturedRequest = req;
+        yield { type: 'text_delta', text: 'done' };
+        yield { type: 'finish', usage: { input: 1, output: 1 }, stopReason: 'end_turn' };
+      },
+      async complete(): Promise<LLMResponse> {
+        throw new Error('not impl');
+      },
+    };
+
+    await runAgentLoop({
+      ctx,
+      provider,
+      events: new EventBus(),
+      retry: new DefaultRetryPolicy(),
+      signal: new AbortController().signal,
+    });
+
+    const toolNames = (capturedRequest!.tools as Array<{ name: string; mutating: boolean }>).map(
+      (t) => t.name,
+    );
+    expect(toolNames).toEqual(['read', 'grep']);
+    expect(ctx.tools).toHaveLength(4);
+  });
+
+  it('sends all tools when ctx.readOnly is false (default)', async () => {
+    const ctx = new AgentContext({
+      model: { provider: 'mock', model: 'test' },
+      projectRoot: '/tmp/project',
+    });
+    ctx.messages.push({ role: 'user', content: [{ type: 'text', text: 'hi' }] });
+
+    ctx.tools = [
+      { name: 'read', mutating: false },
+      { name: 'write', mutating: true },
+    ];
+
+    let capturedRequest: LLMRequest | undefined;
+    const provider: Provider = {
+      name: 'mock',
+      async *stream(req: LLMRequest): AsyncIterable<LLMEvent> {
+        capturedRequest = req;
+        yield { type: 'text_delta', text: 'done' };
+        yield { type: 'finish', usage: { input: 1, output: 1 }, stopReason: 'end_turn' };
+      },
+      async complete(): Promise<LLMResponse> {
+        throw new Error('not impl');
+      },
+    };
+
+    await runAgentLoop({
+      ctx,
+      provider,
+      events: new EventBus(),
+      retry: new DefaultRetryPolicy(),
+      signal: new AbortController().signal,
+    });
+
+    const toolNames = (capturedRequest!.tools as Array<{ name: string }>).map((t) => t.name);
+    expect(toolNames).toEqual(['read', 'write']);
+  });
+
+  it('injects /btw notes at iteration boundary', async () => {
+    const ctx = new AgentContext({
+      model: { provider: 'mock', model: 'test' },
+      projectRoot: '/tmp/project',
+    });
+    ctx.messages.push({ role: 'user', content: [{ type: 'text', text: 'task' }] });
+    ctx.btwNotes.push('also check tests');
+
+    const events = new EventBus();
+    const provider: Provider = {
+      name: 'mock',
+      async *stream(): AsyncIterable<LLMEvent> {
+        yield { type: 'text_delta', text: 'ok' };
+        yield { type: 'finish', usage: { input: 1, output: 1 }, stopReason: 'end_turn' };
+      },
+      async complete(): Promise<LLMResponse> {
+        throw new Error('not impl');
+      },
+    };
+
+    await runAgentLoop({
+      ctx,
+      provider,
+      events,
+      retry: new DefaultRetryPolicy(),
+      signal: new AbortController().signal,
+    });
+
+    expect(ctx.btwNotes).toHaveLength(0);
+    const userMsg = ctx.messages[0]!;
+    expect(userMsg.role).toBe('user');
+    const content = userMsg.content;
+    if (typeof content !== 'string' && Array.isArray(content)) {
+      const btwBlock = content.find((b) => 'text' in b && b.text.includes('BY THE WAY'));
+      expect(btwBlock).toBeTruthy();
+    }
+  });
+});
+
+describe('agent-loop v0.2.2 structured output', () => {
+  it('hides tools and sets tool_choice when structuredOutput is set', async () => {
+    let capturedRequest: LLMRequest | null = null;
+    const provider: Provider = {
+      name: 'mock',
+      async *stream(req: LLMRequest): AsyncIterable<LLMEvent> {
+        capturedRequest = req;
+        yield { type: 'tool_use_start', id: 't1', name: 'structured_output' };
+        yield { type: 'tool_use_input_delta', id: 't1', partialJson: '{"answer":42}' };
+        yield { type: 'tool_use_stop', id: 't1' };
+        yield { type: 'finish', usage: { input: 10, output: 5 }, stopReason: 'tool_use' };
+      },
+      async complete(): Promise<LLMResponse> { throw new Error('not impl'); },
+    };
+    const ctx = new AgentContext({
+      model: { provider: 'anthropic', model: 'claude-sonnet-4-6' },
+      projectRoot: '/tmp',
+      structuredOutput: {
+        name: 'structured_output',
+        schema: { type: 'object', properties: { answer: { type: 'number' } } },
+      },
+    });
+    ctx.tools = [{ name: 'read', mutating: false } as unknown];
+    const events = new EventBus();
+    const result = await runAgentLoop({
+      ctx,
+      provider,
+      events,
+      retry: new DefaultRetryPolicy(),
+      signal: new AbortController().signal,
+      maxIterations: 5,
+    });
+    expect(capturedRequest).not.toBeNull();
+    expect(capturedRequest!.tools).toHaveLength(1);
+    expect((capturedRequest!.tools![0] as { name: string }).name).toBe('structured_output');
+    expect(capturedRequest!.tool_choice).toEqual({ type: 'tool', name: 'structured_output' });
+    expect(result.status).toBe('structured');
+    expect(result.structuredResult).toEqual({ answer: 42 });
+  });
+
+  it('uses ctx.maxTokens instead of hardcoded 8192', async () => {
+    let capturedRequest: LLMRequest | null = null;
+    const provider: Provider = {
+      name: 'mock',
+      async *stream(req: LLMRequest): AsyncIterable<LLMEvent> {
+        capturedRequest = req;
+        yield { type: 'text_delta', text: 'done' };
+        yield { type: 'finish', usage: { input: 5, output: 5 }, stopReason: 'end_turn' };
+      },
+      async complete(): Promise<LLMResponse> { throw new Error('not impl'); },
+    };
+    const ctx = new AgentContext({
+      model: { provider: 'anthropic', model: 'test' },
+      projectRoot: '/tmp',
+      maxTokens: 4096,
+    });
+    ctx.tools = [];
+    const events = new EventBus();
+    await runAgentLoop({
+      ctx,
+      provider,
+      events,
+      retry: new DefaultRetryPolicy(),
+      signal: new AbortController().signal,
+      maxIterations: 5,
+    });
+    expect(capturedRequest!.max_tokens).toBe(4096);
+  });
+
+  it('throws AGENT_STRUCTURED_OUTPUT_NOT_PRODUCED when model does not call structured tool', async () => {
+    const provider: Provider = {
+      name: 'mock',
+      async *stream(): AsyncIterable<LLMEvent> {
+        yield { type: 'text_delta', text: 'no tool call' };
+        yield { type: 'finish', usage: { input: 5, output: 5 }, stopReason: 'end_turn' };
+      },
+      async complete(): Promise<LLMResponse> { throw new Error('not impl'); },
+    };
+    const ctx = new AgentContext({
+      model: { provider: 'anthropic', model: 'test' },
+      projectRoot: '/tmp',
+      structuredOutput: { name: 'structured_output', schema: {} },
+    });
+    ctx.tools = [];
+    const events = new EventBus();
+    const result = await runAgentLoop({
+      ctx,
+      provider,
+      events,
+      retry: new DefaultRetryPolicy(),
+      signal: new AbortController().signal,
+      maxIterations: 5,
+    });
+    expect(result.status).toBe('failed');
+    expect(result.error).toBeInstanceOf(Error);
+  });
+});
+
+describe('runAgentLoop — fallback forwarding', () => {
+  it('accepts a fallback chain option and forwards it without crashing', async () => {
+    const ctx = new AgentContext({
+      model: { provider: 'anthropic', model: 'claude-sonnet-4-6' },
+      projectRoot: '/tmp/p',
+    });
+    ctx.tools = [];
+
+    const provider: Provider = {
+      name: 'anthropic',
+      async *stream() {
+        yield { type: 'text_delta', text: 'done' } as LLMEvent;
+        yield {
+          type: 'finish',
+          usage: { input: 1, output: 1 },
+          stopReason: 'end_turn',
+        } as LLMEvent;
+      },
+      async complete() {
+        return { content: [], usage: { input: 0, output: 0 }, stopReason: 'end_turn' };
+      },
+    };
+
+    const result = await runAgentLoop({
+      ctx: ctx as Context,
+      provider,
+      events: new EventBus(),
+      retry: new DefaultRetryPolicy(),
+      signal: new AbortController().signal,
+      maxIterations: 1,
+      fallback: [{ providerId: 'openai', model: 'gpt-4o-mini', providerFactory: () => undefined }],
+    });
+
+    expect(result.status).toBe('completed');
+  });
+});

package/tests/audit-log.test.ts

@@ -0,0 +1,199 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fsp } from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { DefaultAuditLog } from '../src/session/audit-log.js';
+import { stableStringify } from '../src/session/audit-log.js';
+import type { AuditEntry } from '../src/session/types.js';
+
+let tmpDir: string;
+
+describe('DefaultAuditLog', () => {
+  beforeEach(async () => {
+    tmpDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'fcx-audit-'));
+  });
+  afterEach(async () => {
+    await fsp.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+  });
+
+  it('records an entry and returns it with hash', async () => {
+    const log = new DefaultAuditLog({ dir: tmpDir });
+    const entry = await log.record({
+      sessionId: 'session-1',
+      toolName: 'read',
+      toolUseId: 'tu1',
+      input: { path: 'test.ts' },
+      output: 'file contents',
+      isError: false,
+    });
+    expect(entry.index).toBe(0);
+    expect(entry.prevHash).toBe('0'.repeat(64));
+    expect(entry.hash).toHaveLength(64);
+    expect(entry.toolName).toBe('read');
+  });
+
+  it('chains entries via prevHash', async () => {
+    const log = new DefaultAuditLog({ dir: tmpDir });
+    const e1 = await log.record({
+      sessionId: 's1', toolName: 'read', toolUseId: 'tu1',
+      input: {}, output: 'ok', isError: false,
+    });
+    const e2 = await log.record({
+      sessionId: 's1', toolName: 'write', toolUseId: 'tu2',
+      input: {}, output: 'ok', isError: false,
+    });
+    expect(e2.prevHash).toBe(e1.hash);
+    expect(e2.index).toBe(1);
+  });
+
+  it('verifies a valid chain', async () => {
+    const log = new DefaultAuditLog({ dir: tmpDir });
+    for (let i = 0; i < 5; i++) {
+      await log.record({
+        sessionId: 's1', toolName: 'read', toolUseId: `tu${i}`,
+        input: { i }, output: `result-${i}`, isError: false,
+      });
+    }
+    const result = await log.verify('s1');
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.entries).toBe(5);
+  });
+
+  it('detects tampered entry (hash mismatch)', async () => {
+    const log = new DefaultAuditLog({ dir: tmpDir });
+    await log.record({
+      sessionId: 's1', toolName: 'read', toolUseId: 'tu1',
+      input: { data: 'original' }, output: 'ok', isError: false,
+    });
+    await log.record({
+      sessionId: 's1', toolName: 'read', toolUseId: 'tu2',
+      input: { data: 'original2' }, output: 'ok', isError: false,
+    });
+
+    const fp = path.join(tmpDir, 's1.audit.jsonl');
+    const raw = await fsp.readFile(fp, 'utf8');
+    const lines = raw.trim().split('\n');
+    const tampered = JSON.parse(lines[0]!) as AuditEntry;
+    tampered.input = { data: 'TAMPERED' };
+    lines[0] = JSON.stringify(tampered);
+    await fsp.writeFile(fp, lines.join('\n') + '\n', 'utf8');
+
+    const result = await log.verify('s1');
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.brokenAt).toBe(0);
+      expect(result.reason).toContain('hash mismatch');
+    }
+  });
+
+  it('detects broken chain (prevHash mismatch)', async () => {
+    const log = new DefaultAuditLog({ dir: tmpDir });
+    await log.record({
+      sessionId: 's1', toolName: 'read', toolUseId: 'tu1',
+      input: {}, output: 'ok', isError: false,
+    });
+    await log.record({
+      sessionId: 's1', toolName: 'read', toolUseId: 'tu2',
+      input: {}, output: 'ok', isError: false,
+    });
+
+    const fp = path.join(tmpDir, 's1.audit.jsonl');
+    const raw = await fsp.readFile(fp, 'utf8');
+    const lines = raw.trim().split('\n');
+    const tampered = JSON.parse(lines[1]!) as AuditEntry;
+    tampered.prevHash = 'a'.repeat(64);
+    lines[1] = JSON.stringify(tampered);
+    await fsp.writeFile(fp, lines.join('\n') + '\n', 'utf8');
+
+    const result = await log.verify('s1');
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toContain('prevHash mismatch');
+  });
+
+  it('loads all entries', async () => {
+    const log = new DefaultAuditLog({ dir: tmpDir });
+    for (let i = 0; i < 3; i++) {
+      await log.record({
+        sessionId: 's1', toolName: 'bash', toolUseId: `tu${i}`,
+        input: { cmd: `echo ${i}` }, output: `${i}`, isError: false,
+      });
+    }
+    const entries = await log.load('s1');
+    expect(entries).toHaveLength(3);
+    expect(entries[0]?.toolName).toBe('bash');
+    expect(entries[2]?.output).toBe('2');
+  });
+
+  it('returns empty for missing session', async () => {
+    const log = new DefaultAuditLog({ dir: tmpDir });
+    const entries = await log.load('nonexistent');
+    expect(entries).toHaveLength(0);
+    const result = await log.verify('nonexistent');
+    expect(result.ok).toBe(true);
+  });
+
+  it('handles error results', async () => {
+    const log = new DefaultAuditLog({ dir: tmpDir });
+    const entry = await log.record({
+      sessionId: 's1', toolName: 'bash', toolUseId: 'tu1',
+      input: { cmd: 'rm -rf /' }, output: 'permission denied',
+      isError: true,
+    });
+    expect(entry.isError).toBe(true);
+  });
+
+  it('isolates different sessions', async () => {
+    const log = new DefaultAuditLog({ dir: tmpDir });
+    await log.record({
+      sessionId: 's1', toolName: 'read', toolUseId: 'tu1',
+      input: {}, output: 'a', isError: false,
+    });
+    await log.record({
+      sessionId: 's2', toolName: 'read', toolUseId: 'tu1',
+      input: {}, output: 'b', isError: false,
+    });
+    const e1 = await log.load('s1');
+    const e2 = await log.load('s2');
+    expect(e1).toHaveLength(1);
+    expect(e2).toHaveLength(1);
+    expect(e1[0]?.index).toBe(0);
+    expect(e2[0]?.index).toBe(0);
+  });
+
+  it('survives instance recreation (reads from disk)', async () => {
+    const log1 = new DefaultAuditLog({ dir: tmpDir });
+    await log1.record({
+      sessionId: 's1', toolName: 'read', toolUseId: 'tu1',
+      input: {}, output: 'first', isError: false,
+    });
+
+    const log2 = new DefaultAuditLog({ dir: tmpDir });
+    const entry = await log2.record({
+      sessionId: 's1', toolName: 'read', toolUseId: 'tu2',
+      input: {}, output: 'second', isError: false,
+    });
+    expect(entry.index).toBe(1);
+    const result = await log2.verify('s1');
+    expect(result.ok).toBe(true);
+  });
+});
+
+describe('stableStringify', () => {
+  it('sorts object keys', () => {
+    expect(stableStringify({ b: 1, a: 2 })).toBe('{"a":2,"b":1}');
+  });
+
+  it('sorts nested keys', () => {
+    expect(stableStringify({ z: { y: 1, x: 2 } })).toBe('{"z":{"x":2,"y":1}}');
+  });
+
+  it('preserves array order', () => {
+    expect(stableStringify([3, 1, 2])).toBe('[3,1,2]');
+  });
+
+  it('is deterministic regardless of insertion order', () => {
+    const a = stableStringify({ c: 3, a: 1, b: { z: 26, a: 1 } });
+    const b = stableStringify({ a: 1, b: { a: 1, z: 26 }, c: 3 });
+    expect(a).toBe(b);
+  });
+});