@auto-engineer/narrative 1.3.4 → 1.4.0

package/package.json

@@ -23,9 +23,9 @@
     "typescript": "^5.9.2",
     "zod": "^3.22.4",
     "zod-to-json-schema": "^3.22.3",
-    "@auto-engineer/id": "1.3.4",
-    "@auto-engineer/file-store": "1.3.4",
-    "@auto-engineer/message-bus": "1.3.4"
+    "@auto-engineer/file-store": "1.4.0",
+    "@auto-engineer/id": "1.4.0",
+    "@auto-engineer/message-bus": "1.4.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -35,7 +35,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.3.4",
+  "version": "1.4.0",
   "scripts": {
     "build": "tsx scripts/build.ts",
     "test": "vitest run --reporter=dot",

package/src/index.ts

@@ -19,6 +19,7 @@ export type {
   Integration,
   MessageTarget,
   Origin,
+  Query,
   State,
 } from './types';
 export { createIntegration } from './types';
@@ -81,6 +82,7 @@ export {
   modelSchema,
   NarrativeNamesSchema as NarrativeNamesSystemSchema,
   NarrativeSchema,
+  QuerySchema,
   QuerySliceSchema,
   ReactSliceSchema,
   RuleSchema,
@@ -135,3 +137,5 @@ export type MessageRef = z.infer<typeof MessageRefSchema>;
 // ID assignment utilities
 export { addAutoIds, hasAllIds } from './id';
 export type { ClientSpecNode } from './schema';
+
+export { detectQueryAction, extractQueryNameFromRequest } from './transformers/narrative-to-model/spec-processors';

package/src/loader/ts-utils.ts

@@ -77,7 +77,7 @@ export function parseImports(ts: typeof import('typescript'), fileName: string,
 
 export interface TypeInfo {
   stringLiteral: string;
-  classification?: 'command' | 'event' | 'state';
+  classification?: 'command' | 'event' | 'state' | 'query';
   dataFields?: { name: string; type: string; required: boolean }[];
 }
 
@@ -93,7 +93,7 @@ export interface GivenTypeInfo {
   column: number;
   ordinal: number; // Sequential position within the file
   typeName: string;
-  classification: 'command' | 'event' | 'state';
+  classification: 'command' | 'event' | 'state' | 'query';
 }
 
 function extractDataFieldsFromTypeLiteral(
@@ -136,7 +136,7 @@ function processTypeAlias(
   const baseName = getBaseName(typeRef.typeName);
   if (typeof baseName !== 'string') return;
 
-  if (!['Command', 'Event', 'State'].includes(baseName)) return;
+  if (!['Command', 'Event', 'State', 'Query'].includes(baseName)) return;
 
   const typeArgs = typeRef.typeArguments ?? [];
   if (typeArgs.length === 0) return;
@@ -145,7 +145,7 @@ function processTypeAlias(
   if (!ts.isLiteralTypeNode(firstArg) || !ts.isStringLiteral(firstArg.literal)) return;
 
   const stringLiteral = firstArg.literal.text;
-  const classification = baseName.toLowerCase() as 'command' | 'event' | 'state';
+  const classification = baseName.toLowerCase() as 'command' | 'event' | 'state' | 'query';
 
   // Try to extract the data fields from the 2nd generic arg (if present)
   let dataFields: { name: string; type: string; required: boolean }[] | undefined;
@@ -271,7 +271,7 @@ function extractDataFields(
   return dataFields;
 }
 
-function inferClassificationFromName(stringLiteral: string): 'command' | 'event' | 'state' | undefined {
+function inferClassificationFromName(stringLiteral: string): 'command' | 'event' | 'state' | 'query' | undefined {
   const eventPatterns = ['ed', 'Created', 'Updated', 'Deleted', 'Placed', 'Added', 'Removed', 'Changed'];
   if (eventPatterns.some((pattern) => stringLiteral.endsWith(pattern))) {
     return 'event';
@@ -282,6 +282,11 @@ function inferClassificationFromName(stringLiteral: string): 'command' | 'event'
     return 'command';
   }
 
+  // Query patterns: View*, Get*, List*, Find*, Search*, Fetch*
+  if (/^(View|Get|List|Find|Search|Fetch)[A-Z]/.test(stringLiteral)) {
+    return 'query';
+  }
+
   const statePatterns = ['Summary', 'View', 'Items', 'List', 'Data', 'Info'];
   if (statePatterns.some((pattern) => stringLiteral.endsWith(pattern))) {
     return 'state';
@@ -463,7 +468,7 @@ function classifyBaseGeneric(
   ts: typeof import('typescript'),
   checker: import('typescript').TypeChecker,
   typeRef: import('typescript').TypeReferenceNode,
-): 'event' | 'command' | 'state' | null {
+): 'event' | 'command' | 'state' | 'query' | null {
   // Resolve base symbol (handles aliases and qualified names)
   let sym: import('typescript').Symbol | undefined;
   if (ts.isIdentifier(typeRef.typeName) || ts.isQualifiedName(typeRef.typeName)) {
@@ -476,6 +481,7 @@ function classifyBaseGeneric(
   if (base.endsWith('Event')) return 'event';
   if (base.endsWith('Command')) return 'command';
   if (base.endsWith('State')) return 'state';
+  if (base.endsWith('Query')) return 'query';
   return null;
 }
 
@@ -483,7 +489,7 @@ function tryUnwrapDirectGeneric(
   ts: typeof import('typescript'),
   typeArg: import('typescript').TypeReferenceNode,
   checker: import('typescript').TypeChecker,
-): { typeName: string; classification: 'event' | 'command' | 'state' } | null {
+): { typeName: string; classification: 'event' | 'command' | 'state' | 'query' } | null {
   if (typeArg.typeArguments === undefined || typeArg.typeArguments.length === 0) return null;
 
   const kind = classifyBaseGeneric(ts, checker, typeArg);
@@ -504,7 +510,7 @@ function tryUnwrapTypeAlias(
   typeArg: import('typescript').TypeReferenceNode,
   typeMap: Map<string, TypeInfo>,
   typesByFile: Map<string, Map<string, TypeInfo>>,
-): { typeName: string; classification: 'event' | 'command' | 'state' } | null {
+): { typeName: string; classification: 'event' | 'command' | 'state' | 'query' } | null {
   if (!ts.isIdentifier(typeArg.typeName)) return null;
 
   const typeName = typeArg.typeName.text;
@@ -526,7 +532,7 @@ function tryUnwrapGeneric(
   checker: import('typescript').TypeChecker,
   typeMap: Map<string, TypeInfo>,
   typesByFile: Map<string, Map<string, TypeInfo>>,
-): { typeName: string; classification: 'event' | 'command' | 'state' } | null {
+): { typeName: string; classification: 'event' | 'command' | 'state' | 'query' } | null {
   if (!ts.isTypeReferenceNode(typeArg)) return null;
 
   return tryUnwrapDirectGeneric(ts, typeArg, checker) ?? tryUnwrapTypeAlias(ts, typeArg, typeMap, typesByFile);
@@ -554,7 +560,7 @@ function createGivenTypeInfo(
   node: import('typescript').CallExpression,
   ordinal: number,
   typeName: string,
-  classification: 'event' | 'command' | 'state',
+  classification: 'event' | 'command' | 'state' | 'query',
 ): GivenTypeInfo {
   const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
   return {

package/src/model-to-narrative.specs.ts

@@ -658,6 +658,59 @@ narrative('Test Flow with Rule IDs', 'FLOW-456', () => {
 `);
   });
 
+  it('should correctly generate Query type alias for query messages', async () => {
+    const modelWithQueryMessage: Model = {
+      variant: 'specs',
+      narratives: [
+        {
+          name: 'Workout Flow',
+          id: 'FLOW-001',
+          slices: [],
+        },
+      ],
+      messages: [
+        {
+          type: 'query',
+          name: 'GetWorkoutHistory',
+          fields: [
+            { name: 'memberId', type: 'string', required: true },
+            { name: 'limit', type: 'number', required: false },
+          ],
+          metadata: { version: 1 },
+        },
+        {
+          type: 'event',
+          name: 'WorkoutRecorded',
+          fields: [{ name: 'workoutId', type: 'string', required: true }],
+          source: 'internal',
+          metadata: { version: 1 },
+        },
+      ],
+      integrations: [],
+      modules: [],
+    };
+
+    const code = getCode(await modelToNarrative(modelWithQueryMessage));
+
+    expect(code).toEqual(`import { narrative } from '@auto-engineer/narrative';
+import type { Event, Query } from '@auto-engineer/narrative';
+type GetWorkoutHistory = Query<
+  'GetWorkoutHistory',
+  {
+    memberId: string;
+    limit?: number;
+  }
+>;
+type WorkoutRecorded = Event<
+  'WorkoutRecorded',
+  {
+    workoutId: string;
+  }
+>;
+narrative('Workout Flow', 'FLOW-001', () => {});
+`);
+  });
+
   it('should correctly resolve Date types in messages', async () => {
     const modelWithDateTypes: Model = {
       variant: 'specs',

package/src/schema.ts

@@ -3,7 +3,7 @@ import { z } from 'zod';
 // Message reference for module type ownership
 export const MessageRefSchema = z
   .object({
-    kind: z.enum(['command', 'event', 'state']).describe('Message kind'),
+    kind: z.enum(['command', 'event', 'state', 'query']).describe('Message kind'),
     name: z.string().describe('Message name'),
   })
   .describe('Reference to a message type');
@@ -174,7 +174,11 @@ const StateSchema = BaseMessageSchema.extend({
   type: z.literal('state'),
 }).describe('State/Read Model representing a view of data');
 
-const MessageSchema = z.discriminatedUnion('type', [CommandSchema, EventSchema, StateSchema]);
+const QuerySchema = BaseMessageSchema.extend({
+  type: z.literal('query'),
+}).describe('Query representing a read operation');
+
+const MessageSchema = z.discriminatedUnion('type', [CommandSchema, EventSchema, StateSchema, QuerySchema]);
 
 const BaseSliceSchema = z
   .object({
@@ -417,6 +421,7 @@ export {
   CommandSchema,
   EventSchema,
   StateSchema,
+  QuerySchema,
   IntegrationSchema,
   CommandSliceSchema,
   QuerySliceSchema,

package/src/transformers/model-to-narrative/generators/imports.ts

@@ -35,6 +35,7 @@ export function buildImports(
     command: 'Command',
     event: 'Event',
     state: 'State',
+    query: 'Query',
   };
 
   const flowTypeNames = Array.from(usedMessageTypes)

package/src/transformers/model-to-narrative/generators/types.ts

@@ -2,7 +2,7 @@ import type tsNS from 'typescript';
 import { typeFromString } from '../ast/emit-helpers';
 
 type Message = {
-  type: 'command' | 'event' | 'state';
+  type: 'command' | 'event' | 'state' | 'query';
   name: string;
   fields: { name: string; type: string; required: boolean }[];
 };
@@ -33,10 +33,9 @@ export function buildTypeAliases(ts: typeof tsNS, messages: Message[]): tsNS.Sta
 
     const name = f.createIdentifier(m.name);
 
-    const rhs = f.createTypeReferenceNode(
-      m.type === 'event' ? 'Event' : m.type === 'command' ? 'Command' : 'State',
-      typeArgs,
-    );
+    const baseTypeName =
+      m.type === 'event' ? 'Event' : m.type === 'command' ? 'Command' : m.type === 'query' ? 'Query' : 'State';
+    const rhs = f.createTypeReferenceNode(baseTypeName, typeArgs);
 
     return f.createTypeAliasDeclaration(
       undefined, // No export keyword

package/src/transformers/narrative-to-model/index.ts

@@ -12,7 +12,7 @@ import { resolveInferredType } from './type-inference';
 
 type TypeResolver = (
   t: string,
-  expected?: 'command' | 'event' | 'state',
+  expected?: 'command' | 'event' | 'state' | 'query',
   exampleData?: unknown,
 ) => { resolvedName: string; typeInfo: TypeInfo | undefined };
 
@@ -47,7 +47,7 @@ function getTypesForNarrative(
 function tryResolveFromNarrativeTypes(
   t: string,
   narrativeSpecificTypes: Map<string, TypeInfo>,
-  expected?: 'command' | 'event' | 'state',
+  expected?: 'command' | 'event' | 'state' | 'query',
   exampleData?: unknown,
 ): { resolvedName: string; typeInfo: TypeInfo | undefined } {
   if (t !== 'InferredType') {
@@ -68,7 +68,7 @@ function tryFallbackToUnionTypes(
   resolvedName: string,
   typeInfo: TypeInfo | undefined,
   unionTypes: Map<string, TypeInfo>,
-  expected?: 'command' | 'event' | 'state',
+  expected?: 'command' | 'event' | 'state' | 'query',
   exampleData?: unknown,
 ): { resolvedName: string; typeInfo: TypeInfo | undefined } {
   if (resolvedName !== 'InferredType' && typeInfo) {
@@ -88,7 +88,7 @@ function tryFallbackToUnionTypes(
 function tryResolveFromUnionTypes(
   t: string,
   unionTypes: Map<string, TypeInfo>,
-  expected?: 'command' | 'event' | 'state',
+  expected?: 'command' | 'event' | 'state' | 'query',
   exampleData?: unknown,
 ): { resolvedName: string; typeInfo: TypeInfo | undefined } {
   if (t !== 'InferredType') {
@@ -110,7 +110,7 @@ function createTypeResolver(
 ) {
   return (
     t: string,
-    expected?: 'command' | 'event' | 'state',
+    expected?: 'command' | 'event' | 'state' | 'query',
     exampleData?: unknown,
   ): { resolvedName: string; typeInfo: TypeInfo | undefined } => {
     if (narrativeSpecificTypes) {

package/src/transformers/narrative-to-model/messages.ts

@@ -1,9 +1,9 @@
 import type { Message } from '../../index';
 import type { TypeInfo } from '../../loader/ts-utils';
 
-function mapKindToMessageType(k: 'command' | 'query' | 'reaction'): 'command' | 'event' | 'state' {
+function mapKindToMessageType(k: 'command' | 'query' | 'reaction'): 'command' | 'event' | 'state' | 'query' {
   if (k === 'command') return 'command';
-  if (k === 'query') return 'state';
+  if (k === 'query') return 'query';
   return 'event';
 }
 
@@ -52,7 +52,7 @@ function processStateFields(
 export function createMessage(
   name: string,
   typeInfo: TypeInfo | undefined,
-  messageType: 'command' | 'event' | 'state',
+  messageType: 'command' | 'event' | 'state' | 'query',
 ): Message {
   let fields = buildInitialFields(typeInfo);
 
@@ -81,6 +81,15 @@ export function createMessage(
     };
   }
 
+  if (messageType === 'query') {
+    return {
+      type: 'query',
+      name,
+      fields,
+      metadata,
+    };
+  }
+
   return {
     type: 'state',
     name,

package/src/transformers/narrative-to-model/spec-processors.specs.ts

@@ -0,0 +1,241 @@
+import { describe, expect, it } from 'vitest';
+import type { Message } from '../../index';
+import type { ExampleShapeHints } from './example-shapes';
+import { detectQueryAction, extractQueryNameFromRequest, processWhen } from './spec-processors';
+
+describe('spec-processors', () => {
+  describe('extractQueryNameFromRequest', () => {
+    it('should extract query name from simple GraphQL query', () => {
+      const request = 'query ViewWorkoutPlan { workoutPlan { id } }';
+      expect(extractQueryNameFromRequest(request)).toBe('ViewWorkoutPlan');
+    });
+
+    it('should extract query name from GraphQL query with variables', () => {
+      const request = 'query ViewWorkoutPlan($workoutId: ID!) { workoutPlan(id: $workoutId) { id name } }';
+      expect(extractQueryNameFromRequest(request)).toBe('ViewWorkoutPlan');
+    });
+
+    it('should extract query name case-insensitively', () => {
+      const request = 'QUERY GetUserProfile { user { id } }';
+      expect(extractQueryNameFromRequest(request)).toBe('GetUserProfile');
+    });
+
+    it('should return null for undefined request', () => {
+      expect(extractQueryNameFromRequest(undefined)).toBe(null);
+    });
+
+    it('should return null for empty string', () => {
+      expect(extractQueryNameFromRequest('')).toBe(null);
+    });
+
+    it('should return null for mutation', () => {
+      const request = 'mutation CreateWorkout { createWorkout { id } }';
+      expect(extractQueryNameFromRequest(request)).toBe(null);
+    });
+
+    it('should extract query name from JSON AST format', () => {
+      const ast = {
+        kind: 'Document',
+        definitions: [
+          {
+            kind: 'OperationDefinition',
+            operation: 'query',
+            name: { value: 'ListWorkouts' },
+          },
+        ],
+      };
+      expect(extractQueryNameFromRequest(JSON.stringify(ast))).toBe('ListWorkouts');
+    });
+  });
+
+  describe('detectQueryAction', () => {
+    it('should return true when whenText exactly matches query name from request', () => {
+      const slice = { type: 'query', request: 'query ViewWorkoutPlan($id: ID!) { workoutPlan { id } }' };
+      expect(detectQueryAction('ViewWorkoutPlan', slice)).toBe(true);
+    });
+
+    it('should return true when whenText matches query name case-insensitively', () => {
+      const slice = { type: 'query', request: 'query viewWorkoutPlan { workoutPlan { id } }' };
+      expect(detectQueryAction('ViewWorkoutPlan', slice)).toBe(true);
+    });
+
+    it('should return false for command slices', () => {
+      const slice = { type: 'command', request: 'mutation CreateWorkout { createWorkout { id } }' };
+      expect(detectQueryAction('ViewWorkoutPlan', slice)).toBe(false);
+    });
+
+    it('should return false when no request field is provided (no naming convention fallback)', () => {
+      const slice = { type: 'query' };
+      // Without request field, cannot determine if it's a query action
+      expect(detectQueryAction('ViewWorkoutPlan', slice)).toBe(false);
+      expect(detectQueryAction('GetUserProfile', slice)).toBe(false);
+      expect(detectQueryAction('ListWorkouts', slice)).toBe(false);
+      expect(detectQueryAction('FindUserById', slice)).toBe(false);
+      expect(detectQueryAction('SearchProducts', slice)).toBe(false);
+      expect(detectQueryAction('FetchOrders', slice)).toBe(false);
+    });
+
+    it('should return false for event names in query slices', () => {
+      const slice = { type: 'query', request: 'query ViewWorkoutPlan { workoutPlan { id } }' };
+      expect(detectQueryAction('WorkoutPlanCreated', slice)).toBe(false);
+    });
+
+    it('should return true for case-insensitive match to query name from request', () => {
+      const slice = { type: 'query', request: 'query ViewWorkoutPlan { workoutPlan { id } }' };
+      // Case-insensitive matching works when request field is present
+      expect(detectQueryAction('viewWorkoutPlan', slice)).toBe(true);
+    });
+
+    it('should return false for empty whenText', () => {
+      const slice = { type: 'query', request: 'query ViewWorkoutPlan { workoutPlan { id } }' };
+      expect(detectQueryAction('', slice)).toBe(false);
+    });
+  });
+
+  describe('processWhen', () => {
+    const mockTypeResolver = (t: string) => ({
+      resolvedName: t,
+      typeInfo: undefined,
+    });
+
+    const createEmptyHints = (): ExampleShapeHints => new Map();
+
+    describe('query action detection', () => {
+      it('should create a query message when When is a query action matching request', () => {
+        const messages: Map<string, Message> = new Map();
+        const slice = { type: 'query', request: 'query ViewWorkoutPlan($id: ID!) { workoutPlan { id } }' };
+        const when = { commandRef: 'ViewWorkoutPlan', exampleData: { workoutId: 'wrk_123' } };
+
+        processWhen(when, slice, mockTypeResolver, messages, createEmptyHints());
+
+        // Query message should be created for query actions
+        expect(messages.size).toBe(1);
+        expect(messages.has('ViewWorkoutPlan')).toBe(true);
+        expect(messages.get('ViewWorkoutPlan')?.type).toBe('query');
+      });
+
+      it('should create a message when no request field (cannot detect query action)', () => {
+        const messages: Map<string, Message> = new Map();
+        const slice = { type: 'query' }; // No request field
+        const when = { commandRef: 'ViewWorkoutHistory', exampleData: { userId: 'user_456' } };
+
+        processWhen(when, slice, mockTypeResolver, messages, createEmptyHints());
+
+        // Without request field, cannot detect query action - treats as event
+        expect(messages.size).toBe(1);
+        expect(messages.has('ViewWorkoutHistory')).toBe(true);
+      });
+
+      it('should create a query message when When matches query name from request', () => {
+        const messages: Map<string, Message> = new Map();
+        const slice = { type: 'query', request: 'query GetUserProfile { user { id } }' };
+        const when = { commandRef: 'GetUserProfile', exampleData: { userId: 'user_123' } };
+
+        processWhen(when, slice, mockTypeResolver, messages, createEmptyHints());
+
+        // Query action detected via request field - query message created
+        expect(messages.size).toBe(1);
+        expect(messages.has('GetUserProfile')).toBe(true);
+        expect(messages.get('GetUserProfile')?.type).toBe('query');
+      });
+
+      it('should create a message when When is an event name in query slice', () => {
+        const messages: Map<string, Message> = new Map();
+        const slice = { type: 'query', request: 'query ViewWorkoutPlan { workoutPlan { id } }' };
+        const when = { commandRef: 'WorkoutPlanUpdated', exampleData: { workoutId: 'wrk_123' } };
+
+        processWhen(when, slice, mockTypeResolver, messages, createEmptyHints());
+
+        // Event messages SHOULD be created
+        expect(messages.size).toBe(1);
+        expect(messages.has('WorkoutPlanUpdated')).toBe(true);
+      });
+
+      it('should create a message for command slices regardless of naming', () => {
+        const messages: Map<string, Message> = new Map();
+        const slice = { type: 'command' };
+        const when = { commandRef: 'ViewWorkoutPlan', exampleData: { workoutId: 'wrk_123' } };
+
+        processWhen(when, slice, mockTypeResolver, messages, createEmptyHints());
+
+        // Command messages SHOULD be created even if it looks like a query action name
+        expect(messages.size).toBe(1);
+        expect(messages.has('ViewWorkoutPlan')).toBe(true);
+      });
+    });
+
+    describe('array of When items', () => {
+      it('should create query messages for query action items matching request', () => {
+        const messages: Map<string, Message> = new Map();
+        const slice = { type: 'query', request: 'query ViewWorkoutPlan { workoutPlan { id } }' };
+        const when = [{ commandRef: 'ViewWorkoutPlan', exampleData: { workoutId: 'wrk_123' } }];
+
+        processWhen(when, slice, mockTypeResolver, messages, createEmptyHints());
+
+        // Query action matches request - query message created
+        expect(messages.size).toBe(1);
+        expect(messages.has('ViewWorkoutPlan')).toBe(true);
+        expect(messages.get('ViewWorkoutPlan')?.type).toBe('query');
+      });
+
+      it('should create messages when no request field (cannot detect query action)', () => {
+        const messages: Map<string, Message> = new Map();
+        const slice = { type: 'query' }; // No request field
+        const when = [{ commandRef: 'ViewWorkoutPlan', exampleData: { workoutId: 'wrk_123' } }];
+
+        processWhen(when, slice, mockTypeResolver, messages, createEmptyHints());
+
+        // Without request field, cannot detect query action - message created
+        expect(messages.size).toBe(1);
+        expect(messages.has('ViewWorkoutPlan')).toBe(true);
+      });
+
+      it('should create messages for event items in array', () => {
+        const messages: Map<string, Message> = new Map();
+        const slice = { type: 'query', request: 'query ViewWorkoutPlan { workoutPlan { id } }' };
+        const when = [
+          { commandRef: 'WorkoutPlanCreated', exampleData: { workoutId: 'wrk_123' } },
+          { commandRef: 'WorkoutPlanUpdated', exampleData: { workoutId: 'wrk_123' } },
+        ];
+
+        processWhen(when, slice, mockTypeResolver, messages, createEmptyHints());
+
+        expect(messages.size).toBe(2);
+        expect(messages.has('WorkoutPlanCreated')).toBe(true);
+        expect(messages.has('WorkoutPlanUpdated')).toBe(true);
+      });
+
+      it('should create query message for query action and event message in mixed array', () => {
+        const messages: Map<string, Message> = new Map();
+        const slice = { type: 'query', request: 'query ViewWorkoutPlan { workoutPlan { id } }' };
+        const when = [
+          { commandRef: 'ViewWorkoutPlan', exampleData: { workoutId: 'wrk_123' } }, // Query action - create query message
+          { commandRef: 'WorkoutPlanUpdated', exampleData: { workoutId: 'wrk_123' } }, // Event - create event message
+        ];
+
+        processWhen(when, slice, mockTypeResolver, messages, createEmptyHints());
+
+        expect(messages.size).toBe(2);
+        expect(messages.has('ViewWorkoutPlan')).toBe(true);
+        expect(messages.get('ViewWorkoutPlan')?.type).toBe('query');
+        expect(messages.has('WorkoutPlanUpdated')).toBe(true);
+      });
+    });
+
+    describe('example shape hints collection', () => {
+      it('should collect example hints for query actions', () => {
+        const messages: Map<string, Message> = new Map();
+        const slice = { type: 'query', request: 'query ViewWorkoutPlan { workoutPlan { id } }' };
+        const when = { commandRef: 'ViewWorkoutPlan', exampleData: { workoutId: 'wrk_123', userId: 'user_456' } };
+        const hints = createEmptyHints();
+
+        processWhen(when, slice, mockTypeResolver, messages, hints);
+
+        // Query message created and hints should be collected
+        expect(messages.size).toBe(1);
+        expect(messages.get('ViewWorkoutPlan')?.type).toBe('query');
+        expect(hints.has('ViewWorkoutPlan')).toBe(true);
+      });
+    });
+  });
+});