@opengsd/get-shit-done-redux 1.0.0

package/sdk/src/query/query-fallback-output-classifier.ts

@@ -0,0 +1,31 @@
+import { readFile } from 'node:fs/promises';
+
+export interface FallbackOutputClassification {
+  mode: 'json' | 'text';
+  output: unknown;
+}
+
+async function parseCliQueryJsonOutput(raw: string, projectDir: string): Promise<unknown> {
+  const trimmed = raw.trim();
+  if (trimmed === '') return null;
+  let jsonStr = trimmed;
+  if (jsonStr.startsWith('@file:')) {
+    const rel = jsonStr.slice(6).trim();
+    const { resolvePathUnderProject } = await import('./helpers.js');
+    const filePath = await resolvePathUnderProject(projectDir, rel);
+    jsonStr = await readFile(filePath, 'utf-8');
+  }
+  return JSON.parse(jsonStr);
+}
+
+export async function classifyFallbackOutput(raw: string, projectDir: string): Promise<FallbackOutputClassification> {
+  if (raw.trim() === '') {
+    return { mode: 'text', output: raw };
+  }
+  try {
+    const output = await parseCliQueryJsonOutput(raw, projectDir);
+    return { mode: 'json', output };
+  } catch {
+    return { mode: 'text', output: raw };
+  }
+}

package/sdk/src/query/query-fallback-policy.test.ts

@@ -0,0 +1,13 @@
+import { describe, it, expect } from 'vitest';
+import { canUseCjsFallback, describeFallbackDisabledPolicy } from './query-fallback-policy.js';
+
+describe('query-fallback-policy', () => {
+  it('describes disabled fallback policy', () => {
+    expect(describeFallbackDisabledPolicy()).toContain('GSD_QUERY_FALLBACK=registered');
+  });
+
+  it('reports fallback capability', () => {
+    expect(canUseCjsFallback({ cjsFallbackEnabled: true })).toBe(true);
+    expect(canUseCjsFallback({ cjsFallbackEnabled: false })).toBe(false);
+  });
+});

package/sdk/src/query/query-fallback-policy.ts

@@ -0,0 +1,11 @@
+export interface FallbackPolicyState {
+  cjsFallbackEnabled: boolean;
+}
+
+export function describeFallbackDisabledPolicy(): string {
+  return 'CJS fallback is disabled (GSD_QUERY_FALLBACK=registered).';
+}
+
+export function canUseCjsFallback(policy: FallbackPolicyState): boolean {
+  return policy.cjsFallbackEnabled;
+}

package/sdk/src/query/query-native-dispatch-adapter.ts

@@ -0,0 +1,16 @@
+import type { QueryRegistry } from './registry.js';
+import type { QueryResult } from './utils.js';
+
+export interface QueryNativeDispatchAdapter {
+  dispatch(command: string, args: string[]): Promise<QueryResult>;
+}
+
+export function createQueryNativeDispatchAdapter(
+  registry: QueryRegistry,
+  projectDir: string,
+  ws?: string,
+): QueryNativeDispatchAdapter {
+  return {
+    dispatch: (command, args) => registry.dispatch(command, args, projectDir, ws),
+  };
+}

package/sdk/src/query/query-policy-capability.test.ts

@@ -0,0 +1,10 @@
+import { describe, it, expect } from 'vitest';
+import { QUERY_POLICY_SNAPSHOT, supportsMutationCommand, supportsRawOutputCommand } from './query-policy-capability.js';
+
+describe('query-policy-capability', () => {
+  it('exposes snapshot + predicates', () => {
+    expect(QUERY_POLICY_SNAPSHOT.mutation_commands.length).toBeGreaterThan(0);
+    expect(supportsMutationCommand('state.update')).toBe(true);
+    expect(supportsRawOutputCommand('state.load')).toBe(true);
+  });
+});

package/sdk/src/query/query-policy-capability.ts

@@ -0,0 +1,26 @@
+import {
+  QUERY_MUTATION_COMMANDS_FROM_DEFINITIONS,
+  TRANSPORT_RAW_COMMANDS_FROM_DEFINITIONS,
+  COMMAND_MUTATION_SET,
+  COMMAND_RAW_OUTPUT_SET,
+} from './command-definition.js';
+
+export const QUERY_MUTATION_COMMAND_LIST: readonly string[] = QUERY_MUTATION_COMMANDS_FROM_DEFINITIONS;
+export const TRANSPORT_RAW_COMMANDS: readonly string[] = TRANSPORT_RAW_COMMANDS_FROM_DEFINITIONS;
+
+export const QUERY_POLICY_SNAPSHOT = {
+  mutation_commands: QUERY_MUTATION_COMMAND_LIST,
+  raw_output_commands: TRANSPORT_RAW_COMMANDS,
+} as const;
+
+export function supportsMutationCommand(command: string): boolean {
+  return COMMAND_MUTATION_SET.has(command);
+}
+
+export function supportsRawOutputCommand(command: string): boolean {
+  return COMMAND_RAW_OUTPUT_SET.has(command);
+}
+
+export function isQueryMutationCommand(command: string): boolean {
+  return COMMAND_MUTATION_SET.has(command);
+}

package/sdk/src/query/query-policy-snapshot.test.ts

@@ -0,0 +1,9 @@
+import { describe, it, expect } from 'vitest';
+import { QUERY_POLICY_SNAPSHOT, QUERY_MUTATION_COMMAND_LIST, TRANSPORT_RAW_COMMANDS } from './query-policy-capability.js';
+
+describe('query-policy-snapshot', () => {
+  it('exposes policy constants through one snapshot interface', () => {
+    expect(QUERY_POLICY_SNAPSHOT.mutation_commands).toBe(QUERY_MUTATION_COMMAND_LIST);
+    expect(QUERY_POLICY_SNAPSHOT.raw_output_commands).toBe(TRANSPORT_RAW_COMMANDS);
+  });
+});

package/sdk/src/query/query-registry-capability.test.ts

@@ -0,0 +1,14 @@
+import { describe, it, expect } from 'vitest';
+import { supportsMutationCommand, supportsRawOutputCommand } from './query-policy-capability.js';
+
+describe('query-registry-capability', () => {
+  it('reports mutation command capability', () => {
+    expect(supportsMutationCommand('state.update')).toBe(true);
+    expect(supportsMutationCommand('state.json')).toBe(false);
+  });
+
+  it('reports raw output capability', () => {
+    expect(supportsRawOutputCommand('state.load')).toBe(true);
+    expect(supportsRawOutputCommand('state.json')).toBe(false);
+  });
+});

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

@@ -0,0 +1,44 @@
+import { findProjectRoot } from './helpers.js';
+import { validateWorkstreamName } from '../workstream-utils.js';
+import { readActiveWorkstream } from './active-workstream-store.js';
+
+export interface QueryRuntimeContextInput {
+  projectDir: string;
+  ws?: string;
+}
+
+export interface QueryRuntimeContext {
+  projectDir: string;
+  ws?: string;
+}
+
+/**
+ * Resolve the runtime context for a query invocation.
+ *
+ * Workstream resolution priority:
+ *   1. `--ws <name>` flag (input.ws)
+ *   2. `GSD_WORKSTREAM` environment variable
+ *   3. `.planning/active-workstream` file
+ *   4. Root `.planning/` (no workstream)
+ */
+export function resolveQueryRuntimeContext(input: QueryRuntimeContextInput): QueryRuntimeContext {
+  const projectDir = findProjectRoot(input.projectDir);
+
+  if (input.ws !== undefined) {
+    return {
+      projectDir,
+      ws: validateWorkstreamName(input.ws) ? input.ws : undefined,
+    };
+  }
+
+  const envWs = process.env.GSD_WORKSTREAM;
+  if (envWs && validateWorkstreamName(envWs)) {
+    return { projectDir, ws: envWs };
+  }
+
+  const fileWs = readActiveWorkstream(projectDir);
+  return {
+    projectDir,
+    ws: fileWs ?? undefined,
+  };
+}

package/sdk/src/query/query-unknown-command-hints.test.ts

@@ -0,0 +1,9 @@
+import { describe, it, expect } from 'vitest';
+import { UNKNOWN_COMMAND_HINTS } from './query-unknown-command-hints.js';
+
+describe('query-unknown-command-hints', () => {
+  it('exports stable hint catalog', () => {
+    expect(UNKNOWN_COMMAND_HINTS.length).toBeGreaterThan(1);
+    expect(UNKNOWN_COMMAND_HINTS[0]).toContain('registered `gsd-sdk query`');
+  });
+});

package/sdk/src/query/query-unknown-command-hints.ts

@@ -0,0 +1,5 @@
+export const UNKNOWN_COMMAND_HINTS: readonly string[] = [
+  'Use a registered `gsd-sdk query` subcommand (see sdk/src/query/QUERY-HANDLERS.md).',
+  'Invoke `node …/gsd-tools.cjs` for CJS-only operations.',
+  'Unset GSD_QUERY_FALLBACK or set it to a non-restricted value to enable fallback.',
+] as const;

package/sdk/src/query/registry-assembly-descriptor.ts

@@ -0,0 +1,87 @@
+import type { AliasCatalogEntry } from './command-catalog.js';
+import type { CommandFamily } from './command-manifest.types.js';
+import type { QueryHandler } from './utils.js';
+import {
+  FOUNDATION_STATIC_CATALOG,
+  STATE_SUPPORT_STATIC_CATALOG,
+  MUTATION_SURFACES_STATIC_CATALOG,
+  VERIFY_DECISION_STATIC_CATALOG,
+  DECISION_ROUTING_STATIC_CATALOG,
+} from './command-static-catalog-foundation.js';
+import { DOMAIN_STATIC_CATALOG } from './command-static-catalog-domain.js';
+import { COMMAND_DEFINITIONS_BY_FAMILY, type CommandDefinition } from './command-definition.js';
+import { FAMILY_HANDLERS } from './command-family-handlers.js';
+import type { RegistryAssemblyAliasGroup, RegistryAssemblyStaticGroup } from './registry-assembly-invariants.js';
+
+export interface RegistryAssemblyStep {
+  kind: 'static' | 'alias';
+  key: string;
+}
+
+function toAliasCatalogEntry(entry: CommandDefinition): AliasCatalogEntry {
+  return {
+    canonical: entry.canonical,
+    aliases: entry.aliases,
+  };
+}
+
+function buildAliasGroup(family: CommandFamily): RegistryAssemblyAliasGroup {
+  const definitions = COMMAND_DEFINITIONS_BY_FAMILY[family];
+  const familyHandlers = FAMILY_HANDLERS[family] as Readonly<Record<string, QueryHandler>>;
+  const handlers: Record<string, QueryHandler> = {};
+
+  for (const entry of definitions) {
+    const handler = familyHandlers[entry.handler_key!];
+    if (!handler) continue;
+    handlers[entry.canonical] = handler;
+  }
+
+  return {
+    family,
+    aliases: definitions.map(toAliasCatalogEntry),
+    handlers,
+  };
+}
+
+export const STATIC_CATALOG_GROUPS: readonly RegistryAssemblyStaticGroup[] = [
+  { name: 'FOUNDATION_STATIC_CATALOG', entries: FOUNDATION_STATIC_CATALOG },
+  { name: 'STATE_SUPPORT_STATIC_CATALOG', entries: STATE_SUPPORT_STATIC_CATALOG },
+  { name: 'MUTATION_SURFACES_STATIC_CATALOG', entries: MUTATION_SURFACES_STATIC_CATALOG },
+  { name: 'VERIFY_DECISION_STATIC_CATALOG', entries: VERIFY_DECISION_STATIC_CATALOG },
+  { name: 'DECISION_ROUTING_STATIC_CATALOG', entries: DECISION_ROUTING_STATIC_CATALOG },
+  { name: 'DOMAIN_STATIC_CATALOG', entries: DOMAIN_STATIC_CATALOG },
+] as const;
+
+export const ALIAS_GROUPS: readonly RegistryAssemblyAliasGroup[] = [
+  buildAliasGroup('state'),
+  buildAliasGroup('roadmap'),
+  buildAliasGroup('verify'),
+  buildAliasGroup('validate'),
+  buildAliasGroup('phase'),
+  buildAliasGroup('phases'),
+  buildAliasGroup('init'),
+] as const;
+
+export const STATIC_GROUP_BY_NAME = Object.fromEntries(
+  STATIC_CATALOG_GROUPS.map((group) => [group.name, group]),
+) as Readonly<Record<string, RegistryAssemblyStaticGroup>>;
+
+export const ALIAS_GROUP_BY_FAMILY = Object.fromEntries(
+  ALIAS_GROUPS.map((group) => [group.family, group]),
+) as Readonly<Record<CommandFamily, RegistryAssemblyAliasGroup>>;
+
+export const REGISTRY_ASSEMBLY_PLAN: readonly RegistryAssemblyStep[] = [
+  { kind: 'static', key: 'FOUNDATION_STATIC_CATALOG' },
+  { kind: 'alias', key: 'state' },
+  { kind: 'static', key: 'STATE_SUPPORT_STATIC_CATALOG' },
+  { kind: 'alias', key: 'roadmap' },
+  { kind: 'static', key: 'MUTATION_SURFACES_STATIC_CATALOG' },
+  { kind: 'alias', key: 'verify' },
+  { kind: 'static', key: 'VERIFY_DECISION_STATIC_CATALOG' },
+  { kind: 'alias', key: 'validate' },
+  { kind: 'static', key: 'DECISION_ROUTING_STATIC_CATALOG' },
+  { kind: 'alias', key: 'phase' },
+  { kind: 'alias', key: 'phases' },
+  { kind: 'alias', key: 'init' },
+  { kind: 'static', key: 'DOMAIN_STATIC_CATALOG' },
+] as const;

package/sdk/src/query/registry-assembly-invariants.ts

@@ -0,0 +1,127 @@
+import type { QueryRegistry } from './registry.js';
+import type { QueryHandler } from './utils.js';
+import type { AliasCatalogEntry } from './command-catalog.js';
+
+export interface RegistryAssemblyAliasGroup {
+  family: string;
+  aliases: readonly AliasCatalogEntry[];
+  handlers: Readonly<Record<string, QueryHandler>>;
+}
+
+export interface RegistryAssemblyStaticGroup {
+  name: string;
+  entries: ReadonlyArray<readonly [command: string, handler: QueryHandler]>;
+}
+
+export interface RegistryAssemblyInputs {
+  staticGroups: readonly RegistryAssemblyStaticGroup[];
+  aliasGroups: readonly RegistryAssemblyAliasGroup[];
+  mutationCommands: ReadonlySet<string>;
+  rawOutputPolicyCommands: readonly string[];
+}
+
+export interface RegistryAssemblyInvariantReport {
+  duplicateCommandKeys: string[];
+  aliasCanonicalsMissingHandlers: string[];
+  missingMutationCommands: string[];
+  missingRawOutputPolicyCommands: string[];
+}
+
+export function collectRegistryAssemblyInvariantReport(
+  inputs: RegistryAssemblyInputs,
+  registry?: QueryRegistry,
+): RegistryAssemblyInvariantReport {
+  const counts = new Map<string, number>();
+
+  for (const group of inputs.staticGroups) {
+    for (const [command] of group.entries) {
+      counts.set(command, (counts.get(command) ?? 0) + 1);
+    }
+  }
+
+  for (const group of inputs.aliasGroups) {
+    for (const entry of group.aliases) {
+      counts.set(entry.canonical, (counts.get(entry.canonical) ?? 0) + 1);
+      for (const alias of entry.aliases) {
+        counts.set(alias, (counts.get(alias) ?? 0) + 1);
+      }
+    }
+  }
+
+  const duplicateCommandKeys = toSortedList(
+    Array.from(counts.entries())
+      .filter(([, count]) => count > 1)
+      .map(([command]) => command),
+  );
+
+  const aliasCanonicalsMissingHandlers: string[] = [];
+  for (const group of inputs.aliasGroups) {
+    for (const entry of group.aliases) {
+      if (!group.handlers[entry.canonical]) {
+        aliasCanonicalsMissingHandlers.push(`${group.family}:${entry.canonical}`);
+      }
+    }
+  }
+
+  const missingMutationCommands = registry
+    ? toSortedList(Array.from(inputs.mutationCommands).filter((command) => !registry.has(command)))
+    : [];
+  const missingRawOutputPolicyCommands = registry
+    ? toSortedList(inputs.rawOutputPolicyCommands.filter((command) => !registry.has(command)))
+    : [];
+
+  return {
+    duplicateCommandKeys,
+    aliasCanonicalsMissingHandlers: toSortedList(aliasCanonicalsMissingHandlers),
+    missingMutationCommands,
+    missingRawOutputPolicyCommands,
+  };
+}
+
+function toSortedList(values: Iterable<string>): string[] {
+  return Array.from(values).sort((a, b) => a.localeCompare(b));
+}
+
+export function assertNoDuplicateRegisteredCommands(inputs: RegistryAssemblyInputs): void {
+  const report = collectRegistryAssemblyInvariantReport(inputs);
+  if (report.duplicateCommandKeys.length > 0) {
+    throw new Error(`registry assembly invariant failed: duplicate command keys: ${report.duplicateCommandKeys.join(', ')}`);
+  }
+}
+
+export function assertAliasCanonicalsHaveHandlers(inputs: RegistryAssemblyInputs): void {
+  const report = collectRegistryAssemblyInvariantReport(inputs);
+  if (report.aliasCanonicalsMissingHandlers.length > 0) {
+    throw new Error(`registry assembly invariant failed: alias canonical missing handler: ${report.aliasCanonicalsMissingHandlers.join(', ')}`);
+  }
+}
+
+export function assertMutationCommandsRegistered(
+  registry: QueryRegistry,
+  mutationCommands: ReadonlySet<string>,
+): void {
+  const report = collectRegistryAssemblyInvariantReport({
+    staticGroups: [],
+    aliasGroups: [],
+    mutationCommands,
+    rawOutputPolicyCommands: [],
+  }, registry);
+  if (report.missingMutationCommands.length > 0) {
+    throw new Error(`registry assembly invariant failed: mutation command missing from registry: ${report.missingMutationCommands.join(', ')}`);
+  }
+}
+
+export function assertRawOutputPolicyCommandsRegistered(
+  registry: QueryRegistry,
+  rawOutputPolicyCommands: readonly string[],
+): void {
+  const report = collectRegistryAssemblyInvariantReport({
+    staticGroups: [],
+    aliasGroups: [],
+    mutationCommands: new Set<string>(),
+    rawOutputPolicyCommands,
+  }, registry);
+  if (report.missingRawOutputPolicyCommands.length > 0) {
+    throw new Error(`registry assembly invariant failed: raw-output policy command missing from registry: ${report.missingRawOutputPolicyCommands.join(', ')}`);
+  }
+}

package/sdk/src/query/registry-assembly.test.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect } from 'vitest';
+import { QueryRegistry } from './registry.js';
+import {
+  buildRegistry,
+  createRegistry,
+  decorateRegistryMutations,
+  QUERY_MUTATION_COMMANDS,
+} from './registry-assembly.js';
+import {
+  assertAliasCanonicalsHaveHandlers,
+  assertMutationCommandsRegistered,
+  assertNoDuplicateRegisteredCommands,
+  assertRawOutputPolicyCommandsRegistered,
+  collectRegistryAssemblyInvariantReport,
+  type RegistryAssemblyAliasGroup,
+  type RegistryAssemblyStaticGroup,
+} from './registry-assembly-invariants.js';
+import { REGISTRY_ASSEMBLY_PLAN } from './registry-assembly-descriptor.js';
+
+const noop = async () => ({ data: null });
+
+describe('registry assembly', () => {
+  it('buildRegistry returns registered registry', () => {
+    const registry = buildRegistry();
+    expect(registry.has('state.load')).toBe(true);
+    expect(registry.has('verify-summary')).toBe(true);
+    expect(registry.has('verify.summary')).toBe(true);
+    expect(registry.has('verify summary')).toBe(true);
+  });
+
+  it('createRegistry keeps public seam', () => {
+    const registry = createRegistry();
+    expect(registry).toBeInstanceOf(QueryRegistry);
+    expect(registry.commands().length).toBeGreaterThan(0);
+  });
+
+  it('decorateRegistryMutations is no-op without event stream', () => {
+    const registry = buildRegistry();
+    expect(() => decorateRegistryMutations(registry, undefined, 's')).not.toThrow();
+  });
+
+  it('QUERY_MUTATION_COMMANDS entries are present in registry', () => {
+    const registry = buildRegistry();
+    for (const command of QUERY_MUTATION_COMMANDS) {
+      expect(registry.has(command), `missing mutation command: ${command}`).toBe(true);
+    }
+  });
+
+  it('uses declarative registry assembly plan', () => {
+    expect(REGISTRY_ASSEMBLY_PLAN.length).toBeGreaterThan(0);
+    expect(REGISTRY_ASSEMBLY_PLAN[0]).toEqual({ kind: 'static', key: 'FOUNDATION_STATIC_CATALOG' });
+  });
+});
+
+describe('registry assembly invariants', () => {
+  const staticGroups: RegistryAssemblyStaticGroup[] = [
+    { name: 'S1', entries: [['one', noop]] },
+  ];
+  const aliasGroups: RegistryAssemblyAliasGroup[] = [
+    { family: 'f', aliases: [{ canonical: 'canon', aliases: ['alias'] }], handlers: { canon: noop } },
+  ];
+
+  it('fails on duplicate command keys', () => {
+    expect(() => assertNoDuplicateRegisteredCommands({
+      staticGroups: [
+        { name: 'S1', entries: [['dup', noop]] },
+        { name: 'S2', entries: [['dup', noop]] },
+      ],
+      aliasGroups: [],
+      mutationCommands: new Set<string>(),
+      rawOutputPolicyCommands: [],
+    })).toThrow(/duplicate command keys/i);
+  });
+
+  it('fails on alias canonical without handler', () => {
+    expect(() => assertAliasCanonicalsHaveHandlers({
+      staticGroups: [],
+      aliasGroups: [
+        { family: 'f', aliases: [{ canonical: 'missing', aliases: [] }], handlers: {} },
+      ],
+      mutationCommands: new Set<string>(),
+      rawOutputPolicyCommands: [],
+    })).toThrow(/alias canonical missing handler/i);
+  });
+
+  it('fails when mutation command missing from registry', () => {
+    const registry = new QueryRegistry();
+    expect(() => assertMutationCommandsRegistered(registry, new Set(['missing.cmd']))).toThrow(/mutation command missing from registry/i);
+  });
+
+  it('fails when raw-output policy command missing from registry', () => {
+    const registry = new QueryRegistry();
+    expect(() => assertRawOutputPolicyCommandsRegistered(registry, ['verify-summary'])).toThrow(/raw-output policy command missing from registry/i);
+  });
+
+  it('passes happy path', () => {
+    const registry = new QueryRegistry();
+    registry.register('one', noop);
+    registry.register('canon', noop);
+    registry.register('alias', noop);
+    expect(() => assertNoDuplicateRegisteredCommands({
+      staticGroups,
+      aliasGroups,
+      mutationCommands: new Set<string>(),
+      rawOutputPolicyCommands: [],
+    })).not.toThrow();
+    expect(() => assertAliasCanonicalsHaveHandlers({
+      staticGroups,
+      aliasGroups,
+      mutationCommands: new Set<string>(),
+      rawOutputPolicyCommands: [],
+    })).not.toThrow();
+    expect(() => assertMutationCommandsRegistered(registry, new Set(['one']))).not.toThrow();
+    expect(() => assertRawOutputPolicyCommandsRegistered(registry, ['canon'])).not.toThrow();
+  });
+
+  it('collects invariant report for all failure classes', () => {
+    const registry = new QueryRegistry();
+    const report = collectRegistryAssemblyInvariantReport({
+      staticGroups: [
+        { name: 'S1', entries: [['dup', noop]] },
+        { name: 'S2', entries: [['dup', noop]] },
+      ],
+      aliasGroups: [
+        { family: 'f', aliases: [{ canonical: 'missing', aliases: ['dup'] }], handlers: {} },
+      ],
+      mutationCommands: new Set(['missing.mutation']),
+      rawOutputPolicyCommands: ['missing.raw'],
+    }, registry);
+
+    expect(report).toEqual({
+      duplicateCommandKeys: ['dup'],
+      aliasCanonicalsMissingHandlers: ['f:missing'],
+      missingMutationCommands: ['missing.mutation'],
+      missingRawOutputPolicyCommands: ['missing.raw'],
+    });
+  });
+});

package/sdk/src/query/registry-assembly.ts

@@ -0,0 +1,78 @@
+import { QueryRegistry } from './registry.js';
+import { GSDEventStream } from '../event-stream.js';
+import { registerAliasCatalog, registerStaticCatalog } from './command-catalog.js';
+import { QUERY_MUTATION_COMMAND_LIST, TRANSPORT_RAW_COMMANDS } from './query-policy-capability.js';
+import { decorateMutationsWithEvents } from './mutation-event-decorator.js';
+import {
+  STATIC_CATALOG_GROUPS,
+  ALIAS_GROUPS,
+  STATIC_GROUP_BY_NAME,
+  ALIAS_GROUP_BY_FAMILY,
+  REGISTRY_ASSEMBLY_PLAN,
+} from './registry-assembly-descriptor.js';
+import {
+  assertAliasCanonicalsHaveHandlers,
+  assertMutationCommandsRegistered,
+  assertNoDuplicateRegisteredCommands,
+  assertRawOutputPolicyCommandsRegistered,
+} from './registry-assembly-invariants.js';
+
+/**
+ * Command names that perform durable writes (disk, git, or global profile store).
+ */
+export const QUERY_MUTATION_COMMANDS = new Set<string>(QUERY_MUTATION_COMMAND_LIST);
+
+
+export function buildRegistry(): QueryRegistry {
+  assertAliasCanonicalsHaveHandlers({
+    staticGroups: STATIC_CATALOG_GROUPS,
+    aliasGroups: ALIAS_GROUPS,
+    mutationCommands: QUERY_MUTATION_COMMANDS,
+    rawOutputPolicyCommands: TRANSPORT_RAW_COMMANDS,
+  });
+  assertNoDuplicateRegisteredCommands({
+    staticGroups: STATIC_CATALOG_GROUPS,
+    aliasGroups: ALIAS_GROUPS,
+    mutationCommands: QUERY_MUTATION_COMMANDS,
+    rawOutputPolicyCommands: TRANSPORT_RAW_COMMANDS,
+  });
+
+  const registry = new QueryRegistry();
+
+  for (const step of REGISTRY_ASSEMBLY_PLAN) {
+    if (step.kind === 'static') {
+      const group = STATIC_GROUP_BY_NAME[step.key];
+      if (!group) throw new Error(`registry assembly invariant failed: unknown static group: ${step.key}`);
+      registerStaticCatalog(registry, group.entries);
+      continue;
+    }
+
+    const group = ALIAS_GROUP_BY_FAMILY[step.key as keyof typeof ALIAS_GROUP_BY_FAMILY];
+    if (!group) throw new Error(`registry assembly invariant failed: unknown alias group: ${step.key}`);
+    registerAliasCatalog(registry, group.aliases, group.handlers);
+  }
+
+  assertMutationCommandsRegistered(registry, QUERY_MUTATION_COMMANDS);
+  assertRawOutputPolicyCommandsRegistered(registry, TRANSPORT_RAW_COMMANDS);
+
+  return registry;
+}
+
+export function decorateRegistryMutations(
+  registry: QueryRegistry,
+  eventStream?: GSDEventStream,
+  correlationSessionId?: string,
+): void {
+  if (!eventStream) return;
+  const mutationSessionId = correlationSessionId ?? '';
+  decorateMutationsWithEvents(registry, QUERY_MUTATION_COMMANDS, eventStream, mutationSessionId);
+}
+
+export function createRegistry(
+  eventStream?: GSDEventStream,
+  correlationSessionId?: string,
+): QueryRegistry {
+  const registry = buildRegistry();
+  decorateRegistryMutations(registry, eventStream, correlationSessionId);
+  return registry;
+}