@bhargavvc/sdd-cc 1.35.0 → 1.42.4

package/sdk/src/query-runtime-bridge.ts

@@ -0,0 +1,215 @@
+import type { QueryRegistry } from './query/registry.js';
+import type { TransportMode } from './sdd-transport-policy.js';
+import type { QueryCommandResolution } from './query/query-command-resolution-strategy.js';
+import { resolveQueryCommand } from './query/query-command-resolution-strategy.js';
+import { QueryExecutionPolicy } from './query-execution-policy.js';
+import { QueryNativeHotpathAdapter } from './query-native-hotpath-adapter.js';
+import { SDDToolsError } from './sdd-tools-error.js';
+import type { TransportDecision } from './sdd-transport.js';
+
+export interface RuntimeBridgeExecuteInput {
+  legacyCommand: string;
+  legacyArgs: string[];
+  registryCommand: string;
+  registryArgs: string[];
+  mode: TransportMode;
+  projectDir: string;
+  workstream?: string;
+}
+
+export interface RuntimeBridgeDispatchEvent {
+  type: 'query_dispatch';
+  command: string;
+  legacyCommand: string;
+  mode: TransportMode;
+  dispatchMode: 'native' | 'subprocess' | 'native_hotpath';
+  reason?: TransportDecision['reason'];
+  durationMs: number;
+  outcome: 'success' | 'error';
+  errorKind?: 'timeout' | 'failure';
+}
+
+export interface RuntimeBridgeHotpathEvent {
+  type: 'query_hotpath_dispatch';
+  command: string;
+  legacyCommand: string;
+  mode: TransportMode;
+  dispatchMode: 'native_hotpath' | 'subprocess';
+  reason?: 'native_disabled' | 'policy_blocked';
+  durationMs: number;
+  outcome: 'success' | 'error';
+  errorKind?: 'timeout' | 'failure';
+}
+
+export type RuntimeBridgeEvent = RuntimeBridgeDispatchEvent | RuntimeBridgeHotpathEvent;
+
+export interface RuntimeBridgeOptions {
+  strictSdk?: boolean;
+  allowFallbackToSubprocess?: boolean;
+  onDispatchEvent?: (event: RuntimeBridgeEvent) => void;
+}
+
+/**
+ * SDK Runtime Bridge Module.
+ * Owns dispatch routing through the execution policy seam and hotpath/native fallback behavior.
+ */
+export class QueryRuntimeBridge {
+  constructor(
+    private readonly registry: QueryRegistry,
+    private readonly executionPolicy: QueryExecutionPolicy,
+    private readonly nativeHotpathAdapter: QueryNativeHotpathAdapter,
+    private readonly shouldUseNativeQuery: () => boolean,
+    private readonly options?: RuntimeBridgeOptions,
+  ) {}
+
+  getRegistry(): QueryRegistry {
+    return this.registry;
+  }
+
+  resolve(command: string, args: string[]): QueryCommandResolution | null {
+    return resolveQueryCommand(command, args, this.registry);
+  }
+
+  private emit(event: RuntimeBridgeEvent): void {
+    try {
+      this.options?.onDispatchEvent?.(event);
+    } catch {
+      // Observability must never break dispatch behavior.
+    }
+  }
+
+  async execute(input: RuntimeBridgeExecuteInput): Promise<unknown> {
+    const startedAt = Date.now();
+    if (this.options?.strictSdk && !this.registry.has(input.registryCommand)) {
+      const error = SDDToolsError.failure(
+        `Strict SDK mode: command '${input.registryCommand}' has no native adapter`,
+        input.legacyCommand,
+        input.legacyArgs,
+        null,
+      );
+      this.emit({
+        type: 'query_dispatch',
+        command: input.registryCommand,
+        legacyCommand: input.legacyCommand,
+        mode: input.mode,
+        dispatchMode: 'native',
+        reason: 'native_unregistered',
+        durationMs: Date.now() - startedAt,
+        outcome: 'error',
+        errorKind: 'failure',
+      });
+      throw error;
+    }
+
+    let transportDecision: TransportDecision | undefined;
+    try {
+      const result = await this.executionPolicy.execute({
+        legacyCommand: input.legacyCommand,
+        legacyArgs: input.legacyArgs,
+        registryCommand: input.registryCommand,
+        registryArgs: input.registryArgs,
+        mode: input.mode,
+        projectDir: input.projectDir,
+        workstream: input.workstream,
+        preferNativeQuery: this.shouldUseNativeQuery(),
+        allowFallbackToSubprocess: this.options?.allowFallbackToSubprocess,
+        onTransportDecision: (decision) => {
+          transportDecision = decision;
+        },
+      });
+
+      this.emit({
+        type: 'query_dispatch',
+        command: input.registryCommand,
+        legacyCommand: input.legacyCommand,
+        mode: input.mode,
+        dispatchMode: transportDecision?.dispatchMode ?? 'native',
+        reason: transportDecision?.reason,
+        durationMs: Date.now() - startedAt,
+        outcome: 'success',
+      });
+      return result;
+    } catch (error) {
+      const kind = error instanceof SDDToolsError ? error.classification.kind : 'failure';
+      this.emit({
+        type: 'query_dispatch',
+        command: input.registryCommand,
+        legacyCommand: input.legacyCommand,
+        mode: input.mode,
+        dispatchMode: transportDecision?.dispatchMode ?? 'native',
+        reason: transportDecision?.reason,
+        durationMs: Date.now() - startedAt,
+        outcome: 'error',
+        errorKind: kind,
+      });
+      throw error;
+    }
+  }
+
+  async dispatchHotpath(
+    legacyCommand: string,
+    legacyArgs: string[],
+    registryCommand: string,
+    registryArgs: string[],
+    mode: TransportMode,
+  ): Promise<unknown> {
+    const startedAt = Date.now();
+    const useNative = this.shouldUseNativeQuery();
+
+    if (!useNative && this.options?.allowFallbackToSubprocess === false) {
+      const error = SDDToolsError.failure(
+        `Subprocess fallback disabled: command '${registryCommand}' cannot run without native dispatch`,
+        legacyCommand,
+        legacyArgs,
+        null,
+      );
+      this.emit({
+        type: 'query_hotpath_dispatch',
+        command: registryCommand,
+        legacyCommand,
+        mode,
+        dispatchMode: 'subprocess',
+        reason: 'policy_blocked',
+        durationMs: Date.now() - startedAt,
+        outcome: 'error',
+        errorKind: 'failure',
+      });
+      throw error;
+    }
+
+    try {
+      const result = await this.nativeHotpathAdapter.dispatch(
+        legacyCommand,
+        legacyArgs,
+        registryCommand,
+        registryArgs,
+        mode,
+      );
+      this.emit({
+        type: 'query_hotpath_dispatch',
+        command: registryCommand,
+        legacyCommand,
+        mode,
+        dispatchMode: useNative ? 'native_hotpath' : 'subprocess',
+        reason: useNative ? undefined : 'native_disabled',
+        durationMs: Date.now() - startedAt,
+        outcome: 'success',
+      });
+      return result;
+    } catch (error) {
+      const kind = error instanceof SDDToolsError ? error.classification.kind : 'failure';
+      this.emit({
+        type: 'query_hotpath_dispatch',
+        command: registryCommand,
+        legacyCommand,
+        mode,
+        dispatchMode: useNative ? 'native_hotpath' : 'subprocess',
+        reason: useNative ? undefined : 'native_disabled',
+        durationMs: Date.now() - startedAt,
+        outcome: 'error',
+        errorKind: kind,
+      });
+      throw error;
+    }
+  }
+}

package/sdk/src/query-runtime-seam-coverage.test.ts

@@ -0,0 +1,20 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createSDDToolsRuntime } from './query-sdd-tools-runtime.js';
+
+describe('SDK Runtime Bridge seam coverage', () => {
+  it('exposes bridge as the single runtime seam', () => {
+    const runtime = createSDDToolsRuntime({
+      projectDir: '/tmp/project',
+      sddToolsPath: '/tmp/sdd-tools.cjs',
+      timeoutMs: 1_000,
+      shouldUseNativeQuery: () => true,
+      execJsonFallback: vi.fn(async () => ({})),
+      execRawFallback: vi.fn(async () => ''),
+    });
+
+    expect(Object.keys(runtime)).toEqual(['bridge']);
+    expect(typeof runtime.bridge.resolve).toBe('function');
+    expect(typeof runtime.bridge.execute).toBe('function');
+    expect(typeof runtime.bridge.dispatchHotpath).toBe('function');
+  });
+});

package/sdk/src/query-sdd-tools-path.ts

@@ -0,0 +1 @@
+export { resolveSddToolsPath, BUNDLED_SDD_TOOLS_PATH } from './sdk-package-compatibility.js';

package/sdk/src/query-sdd-tools-runtime.ts

@@ -0,0 +1,89 @@
+import type { SDDEventStream } from './event-stream.js';
+import { createRegistry } from './query/index.js';
+import { SDDTransport } from './sdd-transport.js';
+import { QueryExecutionPolicy } from './query-execution-policy.js';
+import { QuerySubprocessAdapter } from './query-subprocess-adapter.js';
+import { QueryNativeDirectAdapter } from './query-native-direct-adapter.js';
+import { QueryNativeHotpathAdapter } from './query-native-hotpath-adapter.js';
+import { formatQueryRawOutput } from './query-raw-output-projection.js';
+import { createQueryNativeErrorFactory, createQueryToolsErrorFactory } from './query-tools-error-factory.js';
+import { QueryRuntimeBridge, type RuntimeBridgeOptions } from './query-runtime-bridge.js';
+
+export interface SDDToolsRuntime {
+  bridge: QueryRuntimeBridge;
+}
+
+export function createSDDToolsRuntime(opts: {
+  projectDir: string;
+  sddToolsPath: string;
+  timeoutMs: number;
+  workstream?: string;
+  eventStream?: SDDEventStream;
+  sessionId?: string;
+  shouldUseNativeQuery: () => boolean;
+  execJsonFallback: (legacyCommand: string, legacyArgs: string[]) => Promise<unknown>;
+  execRawFallback: (legacyCommand: string, legacyArgs: string[]) => Promise<string>;
+  strictSdk?: boolean;
+  allowFallbackToSubprocess?: boolean;
+  onDispatchEvent?: RuntimeBridgeOptions['onDispatchEvent'];
+}): SDDToolsRuntime {
+  const registry = createRegistry(opts.eventStream, opts.sessionId);
+
+  const queryToolsErrorFactory = createQueryToolsErrorFactory();
+
+  const subprocessAdapter = new QuerySubprocessAdapter({
+    projectDir: opts.projectDir,
+    sddToolsPath: opts.sddToolsPath,
+    timeoutMs: opts.timeoutMs,
+    workstream: opts.workstream,
+    ...queryToolsErrorFactory,
+  });
+
+  const nativeErrorFactory = createQueryNativeErrorFactory(opts.timeoutMs);
+
+  const nativeDirectAdapter = new QueryNativeDirectAdapter({
+    timeoutMs: opts.timeoutMs,
+    // #3591: forward opts.workstream to the registry so native dispatch
+    // routes planning-path queries to .planning/workstreams/<name>/
+    // instead of the root .planning tree. createSDDToolsRuntime accepts
+    // workstream and the QuerySubprocessAdapter already forwards it
+    // (line 38); the native dispatch closure was the only seam that
+    // dropped it, silently routing SDDTools-native queries to root.
+    dispatch: (registryCommand, registryArgs) => registry.dispatch(registryCommand, registryArgs, opts.projectDir, opts.workstream),
+    ...nativeErrorFactory,
+  });
+
+  const transport = new SDDTransport(registry, {
+    dispatchNative: (request) => nativeDirectAdapter.dispatchResult(
+      request.legacyCommand,
+      request.legacyArgs,
+      request.registryCommand,
+      request.registryArgs,
+    ),
+    execSubprocessJson: (legacyCommand, legacyArgs) => subprocessAdapter.execJson(legacyCommand, legacyArgs),
+    execSubprocessRaw: (legacyCommand, legacyArgs) => subprocessAdapter.execRaw(legacyCommand, legacyArgs),
+    formatNativeRaw: (registryCommand, data) => formatQueryRawOutput(registryCommand, data),
+  });
+
+  const executionPolicy = new QueryExecutionPolicy(transport);
+  const nativeHotpathAdapter = new QueryNativeHotpathAdapter(
+    opts.shouldUseNativeQuery,
+    nativeDirectAdapter,
+    opts.execJsonFallback,
+    opts.execRawFallback,
+  );
+
+  const bridge = new QueryRuntimeBridge(
+    registry,
+    executionPolicy,
+    nativeHotpathAdapter,
+    opts.shouldUseNativeQuery,
+    {
+      strictSdk: opts.strictSdk,
+      allowFallbackToSubprocess: opts.allowFallbackToSubprocess,
+      onDispatchEvent: opts.onDispatchEvent,
+    },
+  );
+
+  return { bridge };
+}

package/sdk/src/query-subprocess-adapter.test.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdir, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { QuerySubprocessAdapter } from './query-subprocess-adapter.js';
+
+class FakeToolsError extends Error {
+  constructor(
+    message: string,
+    public readonly command: string,
+    public readonly args: string[],
+    public readonly exitCode: number | null,
+    public readonly stderr: string,
+  ) {
+    super(message);
+  }
+}
+
+describe('QuerySubprocessAdapter', () => {
+  let dir: string;
+  let fixtures: string;
+
+  beforeEach(async () => {
+    dir = join(tmpdir(), `query-subprocess-adapter-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    fixtures = join(dir, 'fixtures');
+    await mkdir(fixtures, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  async function createScript(name: string, code: string): Promise<string> {
+    const scriptPath = join(fixtures, name);
+    await writeFile(scriptPath, code, { mode: 0o755 });
+    return scriptPath;
+  }
+
+  function createAdapter(sddToolsPath: string): QuerySubprocessAdapter {
+    return new QuerySubprocessAdapter({
+      projectDir: dir,
+      sddToolsPath,
+      timeoutMs: 2_000,
+      createTimeoutError: (message, command, args, stderr) =>
+        new FakeToolsError(message, command, args, null, stderr) as never,
+      createFailureError: (message, command, args, exitCode, stderr) =>
+        new FakeToolsError(message, command, args, exitCode, stderr) as never,
+    });
+  }
+
+  it('execJson parses JSON', async () => {
+    const script = await createScript('json.cjs', `process.stdout.write(JSON.stringify({ ok: true }));`);
+    const adapter = createAdapter(script);
+
+    await expect(adapter.execJson('state', ['load'])).resolves.toEqual({ ok: true });
+  });
+
+  it('execJson resolves @file output', async () => {
+    const outFile = join(fixtures, 'out.json');
+    await writeFile(outFile, JSON.stringify({ from: 'file' }));
+    const script = await createScript('file.cjs', `process.stdout.write('@file:${outFile.replace(/\\/g, '\\\\')}');`);
+    const adapter = createAdapter(script);
+
+    await expect(adapter.execJson('state', ['load'])).resolves.toEqual({ from: 'file' });
+  });
+
+  it('execJson resolves relative @file output against projectDir', async () => {
+    const relDir = join(dir, '.planning');
+    await mkdir(relDir, { recursive: true });
+    const relFile = join(relDir, 'out.json');
+    await writeFile(relFile, JSON.stringify({ from: 'relative-file' }));
+    const script = await createScript('file-relative.cjs', `process.stdout.write('@file:.planning/out.json');`);
+    const adapter = createAdapter(script);
+
+    await expect(adapter.execJson('state', ['load'])).resolves.toEqual({ from: 'relative-file' });
+  });
+
+  it('execRaw returns trimmed stdout', async () => {
+    const script = await createScript('raw.cjs', `process.stdout.write('  hello  ');`);
+    const adapter = createAdapter(script);
+
+    await expect(adapter.execRaw('config-set', ['x', 'y'])).resolves.toBe('hello');
+  });
+});

package/sdk/src/query-subprocess-adapter.ts

@@ -0,0 +1,146 @@
+import { execFile } from 'node:child_process';
+import { isAbsolute, resolve } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { timeoutMessage } from './query-failure-classification.js';
+import type { QueryToolsErrorFactory } from './query-tools-error-factory.js';
+
+export interface QuerySubprocessAdapterDeps extends QueryToolsErrorFactory {
+  projectDir: string;
+  sddToolsPath: string;
+  timeoutMs: number;
+  workstream?: string;
+}
+
+export class QuerySubprocessAdapter {
+  constructor(private readonly deps: QuerySubprocessAdapterDeps) {}
+
+  async execJson(command: string, args: string[]): Promise<unknown> {
+    const fullArgs = this.commandArgs(command, args);
+
+    return new Promise<unknown>((resolve, reject) => {
+      const child = execFile(
+        process.execPath,
+        fullArgs,
+        {
+          cwd: this.deps.projectDir,
+          maxBuffer: 10 * 1024 * 1024,
+          timeout: this.deps.timeoutMs,
+          env: { ...process.env },
+        },
+        async (error, stdout, stderr) => {
+          const stderrStr = stderr?.toString() ?? '';
+
+          if (error) {
+            reject(this.processExecutionError(command, args, error, stderrStr));
+            return;
+          }
+
+          const raw = stdout?.toString() ?? '';
+          try {
+            const parsed = await this.parseOutput(raw);
+            resolve(parsed);
+          } catch (parseErr) {
+            reject(
+              this.deps.createFailureError(
+                `Failed to parse sdd-tools output for "${command}": ${parseErr instanceof Error ? parseErr.message : String(parseErr)}\nRaw output: ${raw.slice(0, 500)}`,
+                command,
+                args,
+                0,
+                stderrStr,
+              ),
+            );
+          }
+        },
+      );
+
+      child.on('error', (err) => {
+        reject(this.processSpawnError(command, args, err));
+      });
+    });
+  }
+
+  async execRaw(command: string, args: string[]): Promise<string> {
+    const fullArgs = [...this.commandArgs(command, args), '--raw'];
+
+    return new Promise<string>((resolve, reject) => {
+      const child = execFile(
+        process.execPath,
+        fullArgs,
+        {
+          cwd: this.deps.projectDir,
+          maxBuffer: 10 * 1024 * 1024,
+          timeout: this.deps.timeoutMs,
+          env: { ...process.env },
+        },
+        (error, stdout, stderr) => {
+          const stderrStr = stderr?.toString() ?? '';
+          if (error) {
+            reject(this.processExecutionError(command, args, error, stderrStr));
+            return;
+          }
+          resolve((stdout?.toString() ?? '').trim());
+        },
+      );
+
+      child.on('error', (err) => {
+        reject(this.processSpawnError(command, args, err));
+      });
+    });
+  }
+
+  private commandArgs(command: string, args: string[]): string[] {
+    const wsArgs = this.deps.workstream ? ['--ws', this.deps.workstream] : [];
+    return [this.deps.sddToolsPath, command, ...args, ...wsArgs];
+  }
+
+  private processExecutionError(
+    command: string,
+    args: string[],
+    error: Error & { code?: unknown; status?: number; killed?: boolean },
+    stderrStr: string,
+  ) {
+    if (error.killed || (error as NodeJS.ErrnoException).code === 'ETIMEDOUT') {
+      return this.deps.createTimeoutError(
+        timeoutMessage(command, args, this.deps.timeoutMs),
+        command,
+        args,
+        stderrStr,
+        this.deps.timeoutMs,
+      );
+    }
+
+    return this.deps.createFailureError(
+      `sdd-tools exited with code ${error.code ?? 'unknown'}: ${command} ${args.join(' ')}${stderrStr ? `\n${stderrStr}` : ''}`,
+      command,
+      args,
+      typeof error.code === 'number' ? error.code : error.status ?? 1,
+      stderrStr,
+    );
+  }
+
+  private processSpawnError(command: string, args: string[], err: Error) {
+    return this.deps.createFailureError(`Failed to execute sdd-tools: ${err.message}`, command, args, null, '');
+  }
+
+  private async parseOutput(raw: string): Promise<unknown> {
+    const trimmed = raw.trim();
+
+    if (trimmed === '') {
+      return null;
+    }
+
+    let jsonStr = trimmed;
+    if (jsonStr.startsWith('@file:')) {
+      const filePath = jsonStr.slice(6).trim();
+      const resolvedPath = isAbsolute(filePath) ? filePath : resolve(this.deps.projectDir, filePath);
+      try {
+        jsonStr = await readFile(resolvedPath, 'utf-8');
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to read sdd-tools @file: indirection at "${resolvedPath}": ${reason}`);
+      }
+    }
+
+    return JSON.parse(jsonStr);
+  }
+}

package/sdk/src/query-tools-error-factory.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import { ErrorClassification, SDDError } from './errors.js';
+import {
+  createQueryNativeErrorFactory,
+  createQueryToolsErrorFactory,
+  toToolsErrorFromUnknown,
+} from './query-tools-error-factory.js';
+
+describe('query tools error factory', () => {
+  it('builds timeout and failure tools errors via seam factories', () => {
+    const toolsFactory = createQueryToolsErrorFactory();
+    expect(toolsFactory.createTimeoutError('t', 'state', ['load'], '', 10).classification).toEqual({ kind: 'timeout', timeoutMs: 10 });
+    expect(toolsFactory.createFailureError('f', 'state', ['load'], 1, '').classification).toEqual({ kind: 'failure' });
+  });
+  it('maps SDDError to failure with semantic exit code', () => {
+    const err = toToolsErrorFromUnknown('state', ['load'], new SDDError('bad', ErrorClassification.Validation));
+    expect(err.exitCode).toBe(10);
+    expect(err.classification).toEqual({ kind: 'failure' });
+  });
+
+  it('maps timeout-like unknown errors to timeout classification', () => {
+    const err = toToolsErrorFromUnknown('state', ['load'], new Error('sdd-tools timed out after 50ms: state load'));
+    expect(err.classification).toEqual({ kind: 'timeout', timeoutMs: 50 });
+  });
+
+  it('builds subprocess/native error factories', () => {
+    const toolsFactory = createQueryToolsErrorFactory();
+    const nativeFactory = createQueryNativeErrorFactory(777);
+
+    expect(toolsFactory.createFailureError('x', 'state', ['load'], 1, '').classification).toEqual({ kind: 'failure' });
+    expect(toolsFactory.createTimeoutError('x', 'state', ['load'], '', 123).classification).toEqual({ kind: 'timeout', timeoutMs: 123 });
+    expect(nativeFactory.createNativeTimeoutError('x', 'state', ['load']).classification).toEqual({ kind: 'timeout', timeoutMs: 777 });
+    expect(nativeFactory.createNativeFailureError('x', 'state', ['load'], new Error('boom')).classification).toEqual({ kind: 'failure' });
+  });
+});

package/sdk/src/query-tools-error-factory.ts

@@ -0,0 +1,76 @@
+import { SDDError, exitCodeFor } from './errors.js';
+import { SDDToolsError } from './sdd-tools-error.js';
+import { errorMessage, toFailureSignal } from './query-failure-classification.js';
+
+export interface QueryTimeoutErrorFactory {
+  createTimeoutError: (
+    message: string,
+    command: string,
+    args: string[],
+    stderr: string,
+    timeoutMs: number,
+  ) => SDDToolsError;
+}
+
+export interface QueryFailureErrorFactory {
+  createFailureError: (
+    message: string,
+    command: string,
+    args: string[],
+    exitCode: number | null,
+    stderr: string,
+  ) => SDDToolsError;
+}
+
+export type QueryToolsErrorFactory = QueryTimeoutErrorFactory & QueryFailureErrorFactory;
+
+export interface QueryNativeErrorFactory {
+  createNativeTimeoutError: (message: string, command: string, args: string[]) => SDDToolsError;
+  createNativeFailureError: (message: string, command: string, args: string[], cause: unknown) => SDDToolsError;
+}
+
+function timeoutToolsError(message: string, command: string, args: string[], stderr = '', timeoutMs?: number): SDDToolsError {
+  return SDDToolsError.timeout(message, command, args, stderr, timeoutMs);
+}
+
+function failureToolsError(
+  message: string,
+  command: string,
+  args: string[],
+  exitCode: number | null,
+  stderr = '',
+  cause?: unknown,
+): SDDToolsError {
+  return SDDToolsError.failure(message, command, args, exitCode, stderr, cause === undefined ? undefined : { cause });
+}
+
+export function toToolsErrorFromUnknown(command: string, args: string[], err: unknown): SDDToolsError {
+  if (err instanceof SDDError) {
+    return failureToolsError(err.message, command, args, exitCodeFor(err.classification), '', err);
+  }
+
+  const msg = errorMessage(err);
+  const signal = toFailureSignal(err);
+  if (signal.kind === 'timeout') {
+    return timeoutToolsError(msg, command, args, '', signal.timeoutMs);
+  }
+  return failureToolsError(msg, command, args, 1, '', err instanceof Error ? err : undefined);
+}
+
+export function createQueryToolsErrorFactory(): QueryToolsErrorFactory {
+  return {
+    createTimeoutError: (message, command, args, stderr, timeoutMs) =>
+      timeoutToolsError(message, command, args, stderr, timeoutMs),
+    createFailureError: (message, command, args, exitCode, stderr) =>
+      failureToolsError(message, command, args, exitCode, stderr),
+  };
+}
+
+export function createQueryNativeErrorFactory(defaultTimeoutMs: number): QueryNativeErrorFactory {
+  return {
+    createNativeTimeoutError: (message, command, args) =>
+      timeoutToolsError(message, command, args, '', defaultTimeoutMs),
+    createNativeFailureError: (message, command, args, cause) =>
+      failureToolsError(message, command, args, 1, '', cause),
+  };
+}