refactor(query): deepen command/dispatch seams and resolve coderabbit findings

* refactor(query): deepen command definition seam and fold fallback mapping cleanup

* refactor(query): add shared dispatch formatting module seam

* fix(query): restore QueryResult type import in dispatch deps

* test/query: align raw-output policy and definition normalization contracts

* refactor(query): deepen diagnosis, invariant report, and error taxonomy seams

* refactor(query): deepen dispatch plan, fallback bridge, policy snapshot, and hints seams

* refactor(query): deepen validation, fallback policy, capability, and result builder seams

* refactor(query): deepen resolution strategy, output classifier, observability, and policy-capability seams

* refactor(query): finalize deep strategy/classifier/observability/capability seams

* test/query: address coderabbit inline and out-of-diff dispatch nits

* fix(query): address remaining coderabbit input-validation and bridge stderr threads

* fix(query): address remaining coderabbit dispatch and strategy/output nits

sdk/src/query/query-error-taxonomy.ts

@@ -0,0 +1,98 @@
+import type { QueryDispatchError } from './query-dispatch-contract.js';
+import { fallbackErrorDetails, nativeErrorDetails, unknownCommandDetails } from './query-error-details-schema.js';
+
+export function unknownCommandError(input: {
+  message: string;
+  normalized: string;
+  attempted: string[];
+  hints: string[];
+}): QueryDispatchError {
+  return {
+    kind: 'unknown_command',
+    code: 10,
+    message: input.message,
+    details: unknownCommandDetails({
+      normalized: input.normalized,
+      attempted: input.attempted,
+      hints: input.hints,
+    }) as unknown as Record<string, unknown>,
+  };
+}
+
+export function nativeFailureError(input: {
+  message: string;
+  command: string;
+  args: string[];
+}): QueryDispatchError {
+  return {
+    kind: 'native_failure',
+    code: 1,
+    message: `Error: ${input.message}`,
+    details: nativeErrorDetails({
+      command: input.command,
+      args: input.args,
+    }) as unknown as Record<string, unknown>,
+  };
+}
+
+export function nativeTimeoutError(input: {
+  message: string;
+  command: string;
+  args: string[];
+  timeoutMs?: number;
+}): QueryDispatchError {
+  return {
+    kind: 'native_timeout',
+    code: 1,
+    message: `Error: ${input.message}`,
+    details: nativeErrorDetails({
+      command: input.command,
+      args: input.args,
+      ...(input.timeoutMs !== undefined ? { timeout_ms: input.timeoutMs } : {}),
+    }) as unknown as Record<string, unknown>,
+  };
+}
+
+export function fallbackFailureError(input: {
+  message: string;
+  command: string;
+  args: string[];
+  backend?: 'cjs';
+}): QueryDispatchError {
+  return {
+    kind: 'fallback_failure',
+    code: 1,
+    message: `Error: gsd-tools.cjs fallback failed: ${input.message}`,
+    details: fallbackErrorDetails({
+      command: input.command,
+      args: input.args,
+      backend: input.backend ?? 'cjs',
+    }) as unknown as Record<string, unknown>,
+  };
+}
+
+export function validationError(input: {
+  message: string;
+  code?: number;
+  details?: Record<string, unknown>;
+}): QueryDispatchError {
+  return {
+    kind: 'validation_error',
+    code: input.code ?? 10,
+    message: input.message,
+    details: input.details,
+  };
+}
+
+export function internalError(input: {
+  message: string;
+  code?: number;
+  details?: Record<string, unknown>;
+}): QueryDispatchError {
+  return {
+    kind: 'internal_error',
+    code: input.code ?? 1,
+    message: input.message,
+    details: input.details,
+  };
+}