agentic-orchestrator 0.1.0

package/apps/control-plane/test/tool-registry-loader.spec.ts

@@ -0,0 +1,268 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { MCP_PROTOCOL_PIN, REQUIRED_MCP_TRANSPORTS } from '../src/mcp/protocol-contract.js';
+import { ToolRegistryLoader } from '../src/mcp/tool-registry-loader.js';
+import { ToolsMarkdownGenerator } from '../src/mcp/tools-markdown-generator.js';
+import type { ProtocolContract, ToolCatalog, ToolCatalogEntry } from '../src/mcp/types.js';
+
+const BASE_TOOL: ToolCatalogEntry = {
+  name: 'feature.init',
+  description: 'Initialize feature',
+  input_schema_ref: 'schemas/input/mutating.schema.json',
+  output_schema_ref: 'schemas/output/standard_success.schema.json',
+  supported_roles: ['orchestrator'],
+  handler_id: 'feature.init',
+  mutating: true,
+  requires_operation_id: true
+};
+
+const SECOND_TOOL: ToolCatalogEntry = {
+  name: 'report.dashboard',
+  description: 'Read dashboard',
+  input_schema_ref: 'schemas/input/read.schema.json',
+  output_schema_ref: 'schemas/output/standard_success.schema.json',
+  supported_roles: ['orchestrator'],
+  handler_id: 'report.dashboard',
+  mutating: false,
+  requires_operation_id: false
+};
+
+const VALID_PROTOCOL: ProtocolContract = {
+  mcp_protocol_version: MCP_PROTOCOL_PIN.mcp_protocol_version,
+  sdk: {
+    package: MCP_PROTOCOL_PIN.sdk.package,
+    version: MCP_PROTOCOL_PIN.sdk.version
+  },
+  enabled_transports: [...REQUIRED_MCP_TRANSPORTS, 'inprocess']
+};
+
+const createdRoots: string[] = [];
+
+async function writeJson(filePath: string, payload: unknown): Promise<void> {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+}
+
+async function makeRegistryRepo(overrides?: {
+  catalog?: unknown;
+  protocol?: unknown;
+  tools?: ToolCatalogEntry[];
+  includeErrorsSchema?: boolean;
+  omitSchemas?: string[];
+}): Promise<string> {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-registry-loader-'));
+  createdRoots.push(root);
+  const tools = overrides?.tools ?? [BASE_TOOL];
+  const catalog: ToolCatalog = {
+    version: 1,
+    tools
+  };
+
+  const toolsRoot = path.join(root, 'agentic', 'orchestrator', 'tools');
+  const hasCatalogOverride = overrides ? Object.prototype.hasOwnProperty.call(overrides, 'catalog') : false;
+  const hasProtocolOverride = overrides ? Object.prototype.hasOwnProperty.call(overrides, 'protocol') : false;
+  await writeJson(path.join(toolsRoot, 'catalog.json'), hasCatalogOverride ? overrides?.catalog : catalog);
+  await writeJson(path.join(toolsRoot, 'protocol.json'), hasProtocolOverride ? overrides?.protocol : VALID_PROTOCOL);
+
+  const omitSchemas = new Set(overrides?.omitSchemas ?? []);
+  const refs = new Set<string>();
+  for (const tool of tools) {
+    refs.add(tool.input_schema_ref);
+    refs.add(tool.output_schema_ref);
+  }
+  for (const ref of refs) {
+    if (omitSchemas.has(ref)) {
+      continue;
+    }
+    await writeJson(path.join(toolsRoot, ref), {
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      type: 'object'
+    });
+  }
+
+  if (overrides?.includeErrorsSchema !== false) {
+    await writeJson(path.join(toolsRoot, 'errors.schema.json'), {
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      type: 'object'
+    });
+  }
+
+  return root;
+}
+
+describe('ToolRegistryLoader', () => {
+  afterEach(async () => {
+    await Promise.all(createdRoots.splice(0).map((root) => fs.rm(root, { recursive: true, force: true })));
+  });
+
+  it('GIVEN_valid_registry_WHEN_loading_THEN_returns_lookup_maps_without_side_effects', async () => {
+    const repoRoot = await makeRegistryRepo({ tools: [SECOND_TOOL, BASE_TOOL] });
+    const loader = new ToolRegistryLoader(repoRoot);
+
+    const loaded = await loader.load();
+
+    expect(loaded.toolsByName.get('feature.init')?.handler_id).toBe('feature.init');
+    expect(loaded.toolsByHandlerId.get('report.dashboard')?.name).toBe('report.dashboard');
+    await expect(fs.stat(path.join(repoRoot, 'agentic', 'orchestrator', 'tools.md'))).rejects.toThrow();
+  });
+
+  it('GIVEN_loaded_catalog_WHEN_generating_markdown_THEN_writes_sorted_tools_list', async () => {
+    const repoRoot = await makeRegistryRepo({ tools: [SECOND_TOOL, BASE_TOOL] });
+    const loader = new ToolRegistryLoader(repoRoot);
+    const loaded = await loader.load();
+
+    const generator = new ToolsMarkdownGenerator(repoRoot);
+    await generator.writeFromCatalog(loaded.catalog);
+    const toolsMd = await fs.readFile(path.join(repoRoot, 'agentic', 'orchestrator', 'tools.md'), 'utf8');
+
+    expect(toolsMd).toContain('- feature.init');
+    expect(toolsMd).toContain('- report.dashboard');
+    expect(toolsMd.indexOf('- feature.init')).toBeLessThan(toolsMd.indexOf('- report.dashboard'));
+  });
+
+  it('GIVEN_loader_paths_WHEN_reading_accessors_THEN_resolves_expected_locations', async () => {
+    const repoRoot = await makeRegistryRepo();
+    const loader = new ToolRegistryLoader(repoRoot);
+
+    expect(loader.toolsRoot).toBe(path.join(repoRoot, 'agentic', 'orchestrator', 'tools'));
+    expect(loader.catalogPath).toBe(path.join(loader.toolsRoot, 'catalog.json'));
+    expect(loader.protocolPath).toBe(path.join(loader.toolsRoot, 'protocol.json'));
+    expect(loader.errorsSchemaPath).toBe(path.join(loader.toolsRoot, 'errors.schema.json'));
+    expect(loader.resolveSchemaPath('schemas/input/read.schema.json')).toBe(
+      path.join(loader.toolsRoot, 'schemas', 'input', 'read.schema.json')
+    );
+  });
+
+  it('GIVEN_valid_schemas_WHEN_reading_by_ref_THEN_returns_parsed_schema_payloads', async () => {
+    const repoRoot = await makeRegistryRepo();
+    const loader = new ToolRegistryLoader(repoRoot);
+
+    const inputSchema = await loader.readSchemaByRef(BASE_TOOL.input_schema_ref);
+    const errorsSchema = await loader.readErrorsSchema();
+
+    expect(inputSchema).toMatchObject({ type: 'object' });
+    expect(errorsSchema).toMatchObject({ type: 'object' });
+  });
+
+  it('GIVEN_catalog_with_duplicate_tool_name_WHEN_loading_THEN_throws_duplicate_name_error', async () => {
+    const duplicateName: ToolCatalogEntry = { ...BASE_TOOL, handler_id: 'feature.other_handler' };
+    const repoRoot = await makeRegistryRepo({ tools: [BASE_TOOL, duplicateName] });
+    const loader = new ToolRegistryLoader(repoRoot);
+
+    await expect(loader.load()).rejects.toThrow('registry_duplicate_tool_name:feature.init');
+  });
+
+  it('GIVEN_catalog_with_duplicate_handler_id_WHEN_loading_THEN_throws_duplicate_handler_error', async () => {
+    const duplicateHandler: ToolCatalogEntry = { ...BASE_TOOL, name: 'feature.another' };
+    const repoRoot = await makeRegistryRepo({ tools: [BASE_TOOL, duplicateHandler] });
+    const loader = new ToolRegistryLoader(repoRoot);
+
+    await expect(loader.load()).rejects.toThrow('registry_duplicate_handler_id:feature.init');
+  });
+
+  it('GIVEN_tool_without_supported_roles_WHEN_loading_THEN_throws_supported_roles_missing_error', async () => {
+    const invalidTool: ToolCatalogEntry = { ...BASE_TOOL, supported_roles: [] };
+    const repoRoot = await makeRegistryRepo({ tools: [invalidTool] });
+    const loader = new ToolRegistryLoader(repoRoot);
+
+    await expect(loader.load()).rejects.toThrow('registry_supported_roles_missing:feature.init');
+  });
+
+  it('GIVEN_mutating_tool_without_operation_id_requirement_WHEN_loading_THEN_throws_mutating_contract_error', async () => {
+    const invalidTool: ToolCatalogEntry = { ...BASE_TOOL, requires_operation_id: false };
+    const repoRoot = await makeRegistryRepo({ tools: [invalidTool] });
+    const loader = new ToolRegistryLoader(repoRoot);
+
+    await expect(loader.load()).rejects.toThrow('registry_mutating_requires_operation_id:feature.init');
+  });
+
+  it('GIVEN_missing_input_schema_WHEN_loading_THEN_throws_missing_input_schema_error', async () => {
+    const repoRoot = await makeRegistryRepo({ omitSchemas: [BASE_TOOL.input_schema_ref] });
+    const loader = new ToolRegistryLoader(repoRoot);
+
+    await expect(loader.load()).rejects.toThrow(
+      `registry_missing_input_schema:feature.init:${BASE_TOOL.input_schema_ref}`
+    );
+  });
+
+  it('GIVEN_missing_output_schema_WHEN_loading_THEN_throws_missing_output_schema_error', async () => {
+    const repoRoot = await makeRegistryRepo({ omitSchemas: [BASE_TOOL.output_schema_ref] });
+    const loader = new ToolRegistryLoader(repoRoot);
+
+    await expect(loader.load()).rejects.toThrow(
+      `registry_missing_output_schema:feature.init:${BASE_TOOL.output_schema_ref}`
+    );
+  });
+
+  it('GIVEN_missing_errors_schema_WHEN_loading_THEN_throws_missing_errors_schema_error', async () => {
+    const repoRoot = await makeRegistryRepo({ includeErrorsSchema: false });
+    const loader = new ToolRegistryLoader(repoRoot);
+
+    await expect(loader.load()).rejects.toThrow('registry_missing_errors_schema');
+  });
+
+  it('GIVEN_invalid_catalog_shape_WHEN_loading_THEN_throws_invalid_catalog_shape_error', async () => {
+    const repoRoot = await makeRegistryRepo({ catalog: { version: 1, tools: null } });
+    const loader = new ToolRegistryLoader(repoRoot);
+
+    await expect(loader.load()).rejects.toThrow('registry_invalid_catalog_shape');
+  });
+
+  it('GIVEN_null_protocol_WHEN_loading_THEN_throws_invalid_protocol_shape_error', async () => {
+    const repoRoot = await makeRegistryRepo({ protocol: null });
+    const loader = new ToolRegistryLoader(repoRoot);
+
+    await expect(loader.load()).rejects.toThrow('registry_invalid_protocol_shape');
+  });
+
+  it('GIVEN_protocol_missing_required_fields_WHEN_loading_THEN_throws_invalid_protocol_fields_error', async () => {
+    const repoRoot = await makeRegistryRepo({
+      protocol: { mcp_protocol_version: MCP_PROTOCOL_PIN.mcp_protocol_version, sdk: { package: MCP_PROTOCOL_PIN.sdk.package } }
+    });
+    const loader = new ToolRegistryLoader(repoRoot);
+
+    await expect(loader.load()).rejects.toThrow('registry_invalid_protocol_fields');
+  });
+
+  it('GIVEN_protocol_with_empty_transports_WHEN_loading_THEN_throws_invalid_protocol_transports_error', async () => {
+    const repoRoot = await makeRegistryRepo({
+      protocol: {
+        mcp_protocol_version: MCP_PROTOCOL_PIN.mcp_protocol_version,
+        sdk: { package: MCP_PROTOCOL_PIN.sdk.package, version: MCP_PROTOCOL_PIN.sdk.version },
+        enabled_transports: []
+      }
+    });
+    const loader = new ToolRegistryLoader(repoRoot);
+
+    await expect(loader.load()).rejects.toThrow('registry_invalid_protocol_transports');
+  });
+
+  it('GIVEN_protocol_without_required_stdio_transport_WHEN_loading_THEN_throws_missing_required_transport_error', async () => {
+    const repoRoot = await makeRegistryRepo({
+      protocol: {
+        ...VALID_PROTOCOL,
+        enabled_transports: ['inprocess']
+      }
+    });
+    const loader = new ToolRegistryLoader(repoRoot);
+
+    await expect(loader.load()).rejects.toThrow('registry_missing_required_transport:stdio');
+  });
+
+  it('GIVEN_protocol_pin_values_changed_WHEN_loading_THEN_throws_protocol_pin_mismatch_error', async () => {
+    const repoRoot = await makeRegistryRepo({
+      protocol: {
+        ...VALID_PROTOCOL,
+        sdk: {
+          ...VALID_PROTOCOL.sdk,
+          version: '1.18.1'
+        }
+      }
+    });
+    const loader = new ToolRegistryLoader(repoRoot);
+
+    await expect(loader.load()).rejects.toThrow('registry_protocol_pin_mismatch');
+  });
+});

package/apps/control-plane/test/tool-runtime.spec.ts

@@ -0,0 +1,294 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ERROR_CODES } from '../src/core/error-codes.js';
+import { fail, ok } from '../src/core/response.js';
+import { ToolRuntime } from '../src/mcp/tool-runtime.js';
+import type { ToolCatalogEntry, VerifiedActorClaims } from '../src/mcp/types.js';
+
+const READ_TOOL: ToolCatalogEntry = {
+  name: 'report.dashboard',
+  description: 'Read dashboard',
+  input_schema_ref: 'schemas/input/read.schema.json',
+  output_schema_ref: 'schemas/output/standard_success.schema.json',
+  supported_roles: ['orchestrator'],
+  handler_id: 'report.dashboard',
+  mutating: false,
+  requires_operation_id: false
+};
+
+const MUTATING_TOOL: ToolCatalogEntry = {
+  name: 'feature.init',
+  description: 'Initialize feature',
+  input_schema_ref: 'schemas/input/mutating.schema.json',
+  output_schema_ref: 'schemas/output/standard_success.schema.json',
+  supported_roles: ['orchestrator'],
+  handler_id: 'feature.init',
+  mutating: true,
+  requires_operation_id: true
+};
+
+function claims(overrides: Partial<VerifiedActorClaims> = {}): VerifiedActorClaims {
+  return {
+    run_id: 'run-1',
+    session_id: 'session-1',
+    actor_type: 'orchestrator',
+    actor_id: 'actor-1',
+    issued_at: new Date().toISOString(),
+    expires_at: new Date(Date.now() + 60_000).toISOString(),
+    ...overrides
+  };
+}
+
+function createRuntime() {
+  const registry = {
+    toolsRoot: '/tmp',
+    catalogPath: '/tmp/catalog.json',
+    protocolPath: '/tmp/protocol.json',
+    catalog: { version: 1, tools: [MUTATING_TOOL, READ_TOOL] },
+    protocol: {
+      mcp_protocol_version: '2025-01-01',
+      sdk: { package: 'sdk', version: '1.0.0' },
+      enabled_transports: ['inprocess']
+    },
+    toolsByName: new Map<string, ToolCatalogEntry>([
+      [MUTATING_TOOL.name, MUTATING_TOOL],
+      [READ_TOOL.name, READ_TOOL]
+    ]),
+    toolsByHandlerId: new Map<string, ToolCatalogEntry>([
+      [MUTATING_TOOL.handler_id, MUTATING_TOOL],
+      [READ_TOOL.handler_id, READ_TOOL]
+    ])
+  };
+
+  const loader = {
+    readSchemaByRef: vi.fn(async (schemaRef: string) => ({ $id: schemaRef }))
+  };
+
+  const validator = {
+    validateInput: vi.fn(async () => ({ valid: true, errors: [] })),
+    validateOutput: vi.fn(async () => ({ valid: true, errors: [] })),
+    validateErrorEnvelope: vi.fn(() => ({ valid: true, errors: [] }))
+  };
+
+  const authorizer = {
+    isAuthorized: vi.fn(() => true)
+  };
+
+  const ledger = {
+    resolveOperation: vi.fn(async (): Promise<any> => ({ status: 'new' })),
+    recordOperation: vi.fn(async () => undefined)
+  };
+
+  const executor = {
+    execute: vi.fn(async (): Promise<any> => ok({ payload: 'ok' }))
+  };
+
+  const runtime = new ToolRuntime({
+    registry: registry as any,
+    loader: loader as any,
+    validator: validator as any,
+    authorizer: authorizer as any,
+    ledger: ledger as any,
+    executor: executor as any
+  });
+
+  return { runtime, loader, validator, authorizer, ledger, executor };
+}
+
+describe('ToolRuntime', () => {
+  beforeEach(() => {
+    vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('GIVEN_registry_tools_WHEN_listTools_THEN_returns_sorted_descriptors_with_schemas', async () => {
+    const { runtime, loader } = createRuntime();
+    const descriptors = await runtime.listTools();
+
+    expect(descriptors.map((item) => item.name)).toEqual(['feature.init', 'report.dashboard']);
+    expect(loader.readSchemaByRef).toHaveBeenCalledWith('schemas/input/mutating.schema.json');
+    expect(loader.readSchemaByRef).toHaveBeenCalledWith('schemas/output/standard_success.schema.json');
+  });
+
+  it('GIVEN_unknown_tool_WHEN_calling_THEN_returns_invalid_argument_failure', async () => {
+    const { runtime } = createRuntime();
+    const response = await runtime.callTool('missing.tool', {}, claims());
+
+    expect(response).toMatchObject({
+      ok: false,
+      error: { code: ERROR_CODES.INVALID_ARGUMENT }
+    });
+  });
+
+  it('GIVEN_feature_scope_claim_WHEN_feature_is_out_of_scope_THEN_returns_forbidden', async () => {
+    const { runtime } = createRuntime();
+    const response = await runtime.callTool(
+      READ_TOOL.name,
+      { feature_id: 'feature_b' },
+      claims({ feature_scope: ['feature_a'] })
+    );
+
+    expect(response).toMatchObject({
+      ok: false,
+      error: { code: ERROR_CODES.FORBIDDEN_TOOL_FOR_ROLE }
+    });
+  });
+
+  it('GIVEN_unauthorized_actor_WHEN_calling_tool_THEN_returns_forbidden', async () => {
+    const { runtime, authorizer } = createRuntime();
+    authorizer.isAuthorized.mockReturnValue(false);
+
+    const response = await runtime.callTool(READ_TOOL.name, {}, claims());
+
+    expect(response).toMatchObject({
+      ok: false,
+      error: { code: ERROR_CODES.FORBIDDEN_TOOL_FOR_ROLE }
+    });
+  });
+
+  it('GIVEN_invalid_input_payload_WHEN_calling_tool_THEN_returns_validation_error', async () => {
+    const { runtime, validator } = createRuntime();
+    validator.validateInput.mockResolvedValue({
+      valid: false,
+      errors: [{ message: 'bad input' }]
+    });
+
+    const response = await runtime.callTool(READ_TOOL.name, {}, claims());
+
+    expect(response).toMatchObject({
+      ok: false,
+      error: { code: ERROR_CODES.INVALID_ARGUMENT }
+    });
+  });
+
+  it('GIVEN_mutating_tool_without_operation_id_WHEN_calling_THEN_requires_operation_id', async () => {
+    const { runtime } = createRuntime();
+    const response = await runtime.callTool(MUTATING_TOOL.name, { feature_id: 'feature_a' }, claims());
+
+    expect(response).toMatchObject({
+      ok: false,
+      error: { code: ERROR_CODES.OPERATION_ID_REQUIRED }
+    });
+  });
+
+  it('GIVEN_operation_replay_WHEN_calling_mutating_tool_THEN_returns_recorded_response', async () => {
+    const { runtime, ledger, executor } = createRuntime();
+    ledger.resolveOperation.mockResolvedValue({
+      status: 'replay',
+      response: ok({ cached: true })
+    });
+
+    const response = await runtime.callTool(
+      MUTATING_TOOL.name,
+      { feature_id: 'feature_a', operation_id: 'operation-1234' },
+      claims()
+    );
+
+    expect(response).toEqual(ok({ cached: true }));
+    expect(executor.execute).not.toHaveBeenCalled();
+  });
+
+  it('GIVEN_operation_id_hash_mismatch_WHEN_calling_mutating_tool_THEN_returns_reuse_mismatch_error', async () => {
+    const { runtime, ledger, executor } = createRuntime();
+    ledger.resolveOperation.mockResolvedValue({
+      status: 'mismatch',
+      existing_hash: 'abc123'
+    });
+
+    const response = await runtime.callTool(
+      MUTATING_TOOL.name,
+      { feature_id: 'feature_a', operation_id: 'operation-1234' },
+      claims()
+    );
+
+    expect(response).toMatchObject({
+      ok: false,
+      error: { code: ERROR_CODES.OPERATION_ID_REUSE_MISMATCH }
+    });
+    expect(executor.execute).not.toHaveBeenCalled();
+  });
+
+  it('GIVEN_successful_execution_with_invalid_output_WHEN_validating_output_THEN_returns_internal_error', async () => {
+    const { runtime, validator } = createRuntime();
+    validator.validateOutput.mockResolvedValue({
+      valid: false,
+      errors: [{ message: 'invalid output' }]
+    });
+
+    const response = await runtime.callTool(READ_TOOL.name, {}, claims());
+
+    expect(response).toMatchObject({
+      ok: false,
+      error: { code: ERROR_CODES.INTERNAL_ERROR }
+    });
+  });
+
+  it('GIVEN_failed_execution_with_invalid_error_envelope_WHEN_validating_THEN_returns_internal_error', async () => {
+    const { runtime, executor, validator } = createRuntime();
+    executor.execute.mockResolvedValue(
+      fail(ERROR_CODES.INVALID_ARGUMENT, 'bad request', { retryable: false, requires_human: false })
+    );
+    validator.validateErrorEnvelope.mockReturnValue({
+      valid: false,
+      errors: [{ message: 'invalid envelope' }]
+    });
+
+    const response = await runtime.callTool(READ_TOOL.name, {}, claims());
+    expect(response).toMatchObject({
+      ok: false,
+      error: { code: ERROR_CODES.INTERNAL_ERROR }
+    });
+  });
+
+  it('GIVEN_successful_mutating_call_WHEN_calling_THEN_records_idempotency_entry', async () => {
+    const { runtime, ledger, executor } = createRuntime();
+    executor.execute.mockResolvedValue(ok({ initialized: true }));
+
+    const response = await runtime.callTool(
+      MUTATING_TOOL.name,
+      { feature_id: 'feature_a', operation_id: 'operation-1234' },
+      claims()
+    );
+
+    expect(response).toEqual(ok({ initialized: true }));
+    expect(ledger.recordOperation).toHaveBeenCalledTimes(1);
+  });
+
+  it('GIVEN_retry_with_same_operation_id_after_mutating_failure_WHEN_calling_again_THEN_replays_without_reexecution', async () => {
+    const { runtime, ledger, executor } = createRuntime();
+    const recorded = new Map<string, { requestHash: string; response: ReturnType<typeof fail> }>();
+
+    (ledger.resolveOperation as any).mockImplementation(async (_runId: string, operationId: string, requestHash: string) => {
+      const existing = recorded.get(operationId);
+      if (!existing) {
+        return { status: 'new' };
+      }
+      if (existing.requestHash === requestHash) {
+        return { status: 'replay', response: existing.response };
+      }
+      return { status: 'mismatch', existing_hash: existing.requestHash };
+    });
+    (ledger.recordOperation as any).mockImplementation(
+      async (_runId: string, operationId: string, _toolName: string, requestHash: string, response: ReturnType<typeof fail>) => {
+        recorded.set(operationId, { requestHash, response });
+      }
+    );
+
+    const transientFailure = fail(ERROR_CODES.INTERNAL_ERROR, 'transient_backend_failure', {
+      retryable: true,
+      requires_human: false
+    });
+    executor.execute.mockResolvedValue(transientFailure);
+
+    const args = { feature_id: 'feature_a', operation_id: 'operation-1234' };
+    const first = await runtime.callTool(MUTATING_TOOL.name, args, claims());
+    const second = await runtime.callTool(MUTATING_TOOL.name, args, claims());
+
+    expect(first).toEqual(transientFailure);
+    expect(second).toEqual(transientFailure);
+    expect(executor.execute).toHaveBeenCalledTimes(1);
+    expect(ledger.recordOperation).toHaveBeenCalledTimes(1);
+  });
+});