@auto-engineer/narrative 1.147.0 → 1.149.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @auto-engineer/narrative@1.147.0 build /home/runner/work/auto-engineer/auto-engineer/packages/narrative
+> @auto-engineer/narrative@1.149.0 build /home/runner/work/auto-engineer/auto-engineer/packages/narrative
 > tsx scripts/build.ts
 
 Running: tsc

package/.turbo/turbo-test.log

@@ -1,5 +1,5 @@
 
-> @auto-engineer/narrative@1.146.0 test /home/runner/work/auto-engineer/auto-engineer/packages/narrative
+> @auto-engineer/narrative@1.148.0 test /home/runner/work/auto-engineer/auto-engineer/packages/narrative
 > vitest run --reporter=dot
 
 
@@ -9,6 +9,6 @@
 
  Test Files  22 passed (22)
       Tests  352 passed (352)
-   Start at  19:11:53
-   Duration  49.23s (transform 9.86s, setup 0ms, collect 62.10s, tests 33.40s, environment 40ms, prepare 16.62s)
+   Start at  07:22:59
+   Duration  43.00s (transform 7.80s, setup 0ms, collect 53.89s, tests 31.69s, environment 49ms, prepare 14.81s)
 

package/.turbo/turbo-type-check.log

@@ -1,4 +1,4 @@
 
-> @auto-engineer/narrative@1.146.0 type-check /home/runner/work/auto-engineer/auto-engineer/packages/narrative
+> @auto-engineer/narrative@1.148.0 type-check /home/runner/work/auto-engineer/auto-engineer/packages/narrative
 > tsc --noEmit
 

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # @auto-engineer/flow
 
+## 1.149.0
+
+### Minor Changes
+
+- [`e1eebbd`](https://github.com/BeOnAuto/auto-engineer/commit/e1eebbdf4f209780e790094d2e6887c4fa809f98) Thanks [@github-actions[bot]](https://github.com/github-actions%5Bbot%5D)! - - **server-generator-apollo-emmett**: add Given state ref hints to state.ts.ejs
+  - **server-generator-apollo-emmett**: context-aware nonCommandField instructions
+  - **server-generator-apollo-emmett**: add state context instruction
+  - **server-generator-apollo-emmett**: extract shared template helpers
+  - **server-generator-apollo-emmett**: filter state refs from hasGivenEvents in decide.ts.ejs
+
+### Patch Changes
+
+- [`d38c81e`](https://github.com/BeOnAuto/auto-engineer/commit/d38c81e7bb442a39626564cf4f6d8d55b60d0a38) Thanks [@SamHatoum](https://github.com/SamHatoum)! -
+
+- Updated dependencies [[`d38c81e`](https://github.com/BeOnAuto/auto-engineer/commit/d38c81e7bb442a39626564cf4f6d8d55b60d0a38), [`e1eebbd`](https://github.com/BeOnAuto/auto-engineer/commit/e1eebbdf4f209780e790094d2e6887c4fa809f98)]:
+  - @auto-engineer/file-store@1.149.0
+  - @auto-engineer/id@1.149.0
+  - @auto-engineer/message-bus@1.149.0
+
+## 1.148.0
+
+### Minor Changes
+
+- [`d5ba3a0`](https://github.com/BeOnAuto/auto-engineer/commit/d5ba3a0e3fb0f6a9ad7a3a8b1815590ea77a5b42) Thanks [@rami-hatoum](https://github.com/rami-hatoum)! - - Added state context instruction to generated decide handlers, preventing unnecessary narrowing when Given steps contain only state references
+
+- [`e0cdc4e`](https://github.com/BeOnAuto/auto-engineer/commit/e0cdc4e3363ad84d4bc49996a600ac75c97ccc38) Thanks [@rami-hatoum](https://github.com/rami-hatoum)! - - Added context-aware classification of non-command fields in generated decide.ts scaffolds, distinguishing between date-derived, state-derived, and not-yet-tested fields
+
+- [`9195db7`](https://github.com/BeOnAuto/auto-engineer/commit/9195db78cb707d658866cee99a1c73d34fb4efde) Thanks [@rami-hatoum](https://github.com/rami-hatoum)! - - Extracted shared template helpers into a dedicated module for cleaner code generation
+
+- [`abb6540`](https://github.com/BeOnAuto/auto-engineer/commit/abb6540db7196ed7935c8a8610695828f9035fc3) Thanks [@rami-hatoum](https://github.com/rami-hatoum)! - - Added status variant hints from Given state references to the state template, helping implementers create matching discriminated union variants
+
+- [`9195db7`](https://github.com/BeOnAuto/auto-engineer/commit/9195db78cb707d658866cee99a1c73d34fb4efde) Thanks [@rami-hatoum](https://github.com/rami-hatoum)! - - Extracted shared template helper functions into a dedicated module for better code reuse across generators
+  - Simplified template specs by removing inline duplicate definitions in favor of the shared helpers
+
+### Patch Changes
+
+- [`88fb1da`](https://github.com/BeOnAuto/auto-engineer/commit/88fb1da2b222de04dd4959d87657395ee960a6ce) Thanks [@github-actions[bot]](https://github.com/github-actions%5Bbot%5D)! - - **server-generator-apollo-emmett**: skip empty file plans in scaffold output
+  - **server-generator-apollo-emmett**: filter state refs from given() in decide.specs.ts.ejs
+  - **server-generator-apollo-emmett**: move CS Given states from events to states array
+  - **global**: version packages
+  - **server-generator-apollo-emmett**: mark G1+G2 ketchup plan complete
+
+- [`4255f6d`](https://github.com/BeOnAuto/auto-engineer/commit/4255f6db0d128979e573244a615886482ce799b0) Thanks [@rami-hatoum](https://github.com/rami-hatoum)! - - Updated ketchup plan for state reference fix in decide template generator
+  - Marked generator bug fix milestones G1 and G2 as complete
+
+- [`62f1ea3`](https://github.com/BeOnAuto/auto-engineer/commit/62f1ea3dd1b4275211574e3df9d9a6571ae9b27a) Thanks [@rami-hatoum](https://github.com/rami-hatoum)! - - Fixed scaffold generation to correctly distinguish between event and state references in decision handlers
+  - Prevented contradictory instructions from appearing in generated code when Given clauses contain only state references
+
+- [`ba4f5c9`](https://github.com/BeOnAuto/auto-engineer/commit/ba4f5c9749fb1c15d444e78ca9a2689817f039cb) Thanks [@rami-hatoum](https://github.com/rami-hatoum)! - - Added implementation plan for decide.ts code generation fixes in the Apollo Emmett server generator
+
+- Updated dependencies [[`88fb1da`](https://github.com/BeOnAuto/auto-engineer/commit/88fb1da2b222de04dd4959d87657395ee960a6ce), [`d5ba3a0`](https://github.com/BeOnAuto/auto-engineer/commit/d5ba3a0e3fb0f6a9ad7a3a8b1815590ea77a5b42), [`e0cdc4e`](https://github.com/BeOnAuto/auto-engineer/commit/e0cdc4e3363ad84d4bc49996a600ac75c97ccc38), [`4255f6d`](https://github.com/BeOnAuto/auto-engineer/commit/4255f6db0d128979e573244a615886482ce799b0), [`9195db7`](https://github.com/BeOnAuto/auto-engineer/commit/9195db78cb707d658866cee99a1c73d34fb4efde), [`abb6540`](https://github.com/BeOnAuto/auto-engineer/commit/abb6540db7196ed7935c8a8610695828f9035fc3), [`9195db7`](https://github.com/BeOnAuto/auto-engineer/commit/9195db78cb707d658866cee99a1c73d34fb4efde), [`62f1ea3`](https://github.com/BeOnAuto/auto-engineer/commit/62f1ea3dd1b4275211574e3df9d9a6571ae9b27a), [`ba4f5c9`](https://github.com/BeOnAuto/auto-engineer/commit/ba4f5c9749fb1c15d444e78ca9a2689817f039cb)]:
+  - @auto-engineer/file-store@1.148.0
+  - @auto-engineer/id@1.148.0
+  - @auto-engineer/message-bus@1.148.0
+
 ## 1.147.0
 
 ### Minor Changes

package/README.md

@@ -1,16 +1,25 @@
-# @auto-engineer/narrative
-
-TypeScript DSL for defining business scenes using BDD patterns with Given/When/Then syntax.
-
----
+# @auto-engineer/narrative — Fluent TypeScript DSL for defining behavioral specifications as scenes, moments, and examples
 
 ## Purpose
 
-Without `@auto-engineer/narrative`, you would have to manually structure behavioral specifications, write boilerplate for command/query definitions, and handle the conversion between specification code and JSON models.
+Without `@auto-engineer/narrative`, you would have to hand-write JSON model files describing your system's scenes, moments, messages, data flows, and BDD specifications — then manually keep them in sync with your TypeScript types. This package provides a fluent DSL that lets you author `.narrative.ts` files, automatically extracts type information from your code, and bidirectionally transforms between the DSL representation and a canonical JSON model.
+
+## Key Concepts
 
-This package enables developers to express system behavior through scenes containing moments (commands, queries, reactions, experiences). Each moment supports client and server specifications using Gherkin-style Given/When/Then syntax.
+- **Scene** — A top-level container grouping related moments (e.g., "Place order"). Defined with the `scene()` function.
+- **Moment** — A single interaction point within a scene. Four types exist: `command` (user-triggered state changes), `query` (data reads), `react` (automated responses to events), and `experience` (client-only UI behavior).
+- **Spec / Rule / Example** — BDD-style specifications nested inside moments. A spec contains rules; a rule contains examples; an example contains Given/When/Then steps.
+- **Data flow** — `sink`, `source`, and `target` builders describe how messages route between streams, projections, databases, integrations, and topics.
+- **Model** — The canonical JSON representation (`Model` type) holding scenes, messages, integrations, modules, and narratives. Validated by Zod schemas.
+- **Integration** — An external service (e.g., MailChimp, Twilio) wrapped with `createIntegration()` and referenced via the `via()` builder method.
 
----
+```mermaid
+graph TD
+    A[".narrative.ts files"] -->|getScenes / executeAST| B["Scene[]"]
+    B -->|scenesToModel| C["Model (JSON)"]
+    C -->|modelToNarrative| A
+    C -->|Zod schemas| D["Validation"]
+```
 
 ## Installation
 
@@ -21,173 +30,535 @@ pnpm add @auto-engineer/narrative
 ## Quick Start
 
 ```typescript
-import { flow, command, specs, rule, example, type Event, type Command } from '@auto-engineer/narrative';
+import {
+  scene,
+  command,
+  specs,
+  rule,
+  example,
+  data,
+  sink,
+  source,
+  describe,
+  it,
+} from '@auto-engineer/narrative';
 
-type OrderPlaced = Event<'OrderPlaced', { orderId: string }>;
-type PlaceOrder = Command<'PlaceOrder', { productId: string }>;
+// Define message types alongside your narrative
+interface PlaceOrder {
+  type: 'PlaceOrder';
+  data: { productId: string; quantity: number };
+}
 
-flow('Orders', () => {
-  command('Place order')
+interface OrderPlaced {
+  type: 'OrderPlaced';
+  data: { orderId: string; productId: string; quantity: number };
+}
+
+scene('Place order', () => {
+  command('Submit order')
+    .stream('order-${orderId}')
+    .client(() => {
+      describe('Order submission form', () => {
+        it('allows product selection');
+        it('allows quantity input');
+      });
+    })
     .server(() => {
-      specs('Order placement', () => {
-        rule('Valid orders are processed', () => {
-          example('User places order')
-            .when<PlaceOrder>({ productId: 'p-001' })
-            .then<OrderPlaced>({ orderId: 'o-001' });
+      data([
+        sink().event('OrderPlaced').toStream('order-${orderId}'),
+        source().state('OrderSummary').fromProjection('OrderSummary', 'orderId'),
+      ]);
+
+      specs('User submits a new order', () => {
+        rule('Valid orders should be processed', () => {
+          example('User places order for available product')
+            .when<PlaceOrder>({ productId: 'product_789', quantity: 3 })
+            .then<OrderPlaced>({
+              orderId: 'order_001',
+              productId: 'product_789',
+              quantity: 3,
+            });
         });
       });
     });
 });
 ```
 
----
-
 ## How-to Guides
 
-### Define a Command Moment
+### Define a query moment
 
 ```typescript
-import { flow, command, specs, rule, example } from '@auto-engineer/narrative';
+import { scene, query, specs, rule, example, data, source } from '@auto-engineer/narrative';
 
-flow('Users', () => {
-  command('Create user')
-    .stream('user-${userId}')
+scene('View orders', () => {
+  query('Get order summary')
+    .client(() => {
+      describe('Order list', () => {
+        it('displays order details');
+      });
+    })
     .server(() => {
-      specs('User creation', () => {
-        rule('Valid users created', () => {
-          example('New user')
-            .when({ name: 'John' })
-            .then({ userId: 'u-001' });
+      data([
+        source().state('OrderSummary').fromProjection('OrderSummary', 'orderId'),
+      ]);
+
+      specs('Fetching order data', () => {
+        rule('Returns matching orders', () => {
+          example('Order exists')
+            .given<OrderSummary>({ orderId: 'order_001', productId: 'p1', quantity: 2 })
+            .when<GetOrderSummary>({ orderId: 'order_001' })
+            .then<OrderSummary>({ orderId: 'order_001', productId: 'p1', quantity: 2 });
         });
       });
     });
 });
 ```
 
-### Define a Query Moment
+### Define a reaction moment
 
 ```typescript
-import { flow, query, describe, it, data, source } from '@auto-engineer/narrative';
+import { scene, react, specs, rule, example, createIntegration } from '@auto-engineer/narrative';
 
-flow('Products', () => {
-  query('View products')
-    .client(() => {
-      describe('Product list', () => {
-        it('displays all products');
-      });
-    })
+const emailService = createIntegration('email', 'EmailService');
+
+scene('Order confirmation', () => {
+  react('Send confirmation email')
+    .via(emailService)
     .server(() => {
-      data([source().state('Products').fromProjection('ProductsProjection', 'id')]);
+      specs('Email sent on order placement', () => {
+        rule('Confirmation email is sent', () => {
+          example('Order placed triggers email')
+            .given<OrderPlaced>({ orderId: 'order_001', productId: 'p1', quantity: 2 })
+            .then<ConfirmationEmailSent>({ orderId: 'order_001' });
+        });
+      });
     });
 });
 ```
 
-### Define Data Sinks and Sources
+### Define data sinks and sources
 
 ```typescript
-import { flow, command, data, sink, source } from '@auto-engineer/narrative';
+import { data, sink, source, target } from '@auto-engineer/narrative';
 
-flow('Payments', () => {
-  command('Process payment')
-    .server(() => {
-      data([
-        sink().event('PaymentProcessed').toStream('payment-${paymentId}'),
-        source().state('Account').fromProjection('Accounts', 'accountId'),
-      ]);
-    });
+// Event to stream
+sink().event('OrderPlaced').toStream('order-${orderId}');
+
+// Event to integration
+sink().event('OrderPlaced').toIntegration(emailService);
+
+// Event to database
+sink().event('OrderPlaced').toDatabase('orders');
+
+// Command to integration with message routing
+sink().command('SendEmail').toIntegration(emailService, 'SendEmail', 'command');
+
+// State from projection
+source().state('OrderSummary').fromProjection('OrderSummary', 'orderId');
+
+// State from singleton projection
+source().state('DashboardStats').fromSingletonProjection('DashboardStats');
+
+// State from API
+source().state('ExternalData').fromApi('/api/data', 'GET');
+
+// Event target (declaration only, no routing)
+target().event('OrderPlaced');
+```
+
+### Load narrative files and produce a model
+
+```typescript
+import { getScenes } from '@auto-engineer/narrative';
+
+const result = await getScenes({
+  vfs,   // IFileStore instance
+  root: '/path/to/narratives',
 });
+
+console.log(result.scenes);        // Scene[]
+const model = result.toModel();    // Model (full JSON specification)
+```
+
+### Convert a model back to narrative files
+
+```typescript
+import { modelToNarrative } from '@auto-engineer/narrative';
+
+const generated = await modelToNarrative(model);
+for (const file of generated.files) {
+  console.log(file.path, file.code);
+}
 ```
 
-### Load Scenes from File System
+### Add auto-generated IDs to a model
 
 ```typescript
-import { getNarratives } from '@auto-engineer/narrative';
-import { NodeFileStore } from '@auto-engineer/file-store';
+import { addAutoIds, hasAllIds } from '@auto-engineer/narrative';
 
-const vfs = new NodeFileStore();
-const result = await getNarratives({ vfs, root: '/path/to/src' });
-const model = result.toModel();
+if (!hasAllIds(model)) {
+  const withIds = addAutoIds(model);
+}
 ```
 
----
+### Validate moment requests against the model
+
+```typescript
+import { validateMomentRequests } from '@auto-engineer/narrative';
+
+const errors = validateMomentRequests(model);
+if (errors.length > 0) {
+  errors.forEach((e) => console.error(`${e.sceneName}/${e.momentName}: ${e.message}`));
+}
+```
 
 ## API Reference
 
-### Package Exports
+### Subpath exports
+
+| Import path | Description |
+|---|---|
+| `@auto-engineer/narrative` | Main entry — DSL functions, builders, transformers, and all schema re-exports |
+| `@auto-engineer/narrative/schema` | Zod schemas and inferred TypeScript types for the model |
+| `@auto-engineer/narrative/node` | Re-exports everything from the main entry (Node.js convenience alias) |
+
+### Scene and moment DSL
 
 ```typescript
-import {
-  flow, narrative,
-  command, query, react, experience,
-  specs, rule, example, describe, it, should,
-  client, server, data,
-  sink, source,
-  getNarratives, modelToNarrative,
-  addAutoIds, hasAllIds,
-  gql,
-  type Event, type Command, type State,
-} from '@auto-engineer/narrative';
+function scene(name: string, fn: () => void): void;
+function scene(name: string, id: string, fn: () => void): void;
+
+function command(name: string, id?: string): FluentCommandMomentBuilder;
+function query(name: string, id?: string): FluentQueryMomentBuilder;
+function react(name: string, id?: string): FluentReactionMomentBuilder;
+function experience(name: string, id?: string): FluentExperienceMomentBuilder;
+
+// Aliases
+function decide(name: string, id?: string): FluentCommandMomentBuilder;
+function evolve(name: string, id?: string): FluentQueryMomentBuilder;
+```
+
+### Fluent moment builders
+
+```typescript
+interface FluentCommandMomentBuilder {
+  stream(name: string): FluentCommandMomentBuilder;
+  client(fn: () => void): FluentCommandMomentBuilder;
+  client(description: string, fn: () => void): FluentCommandMomentBuilder;
+  server(fn: () => void): FluentCommandMomentBuilder;
+  server(description: string, fn: () => void): FluentCommandMomentBuilder;
+  via(integration: Integration | Integration[]): FluentCommandMomentBuilder;
+  retries(count: number): FluentCommandMomentBuilder;
+  request(mutation: unknown): FluentCommandMomentBuilder;
+}
+
+interface FluentQueryMomentBuilder {
+  client(fn: () => void): FluentQueryMomentBuilder;
+  client(description: string, fn: () => void): FluentQueryMomentBuilder;
+  server(fn: () => void): FluentQueryMomentBuilder;
+  server(description: string, fn: () => void): FluentQueryMomentBuilder;
+  request(query: unknown): FluentQueryMomentBuilder;
+}
+
+interface FluentReactionMomentBuilder {
+  server(fn: () => void): FluentReactionMomentBuilder;
+  server(description: string, fn: () => void): FluentReactionMomentBuilder;
+  via(integration: Integration | Integration[]): FluentReactionMomentBuilder;
+  retries(count: number): FluentReactionMomentBuilder;
+}
+
+interface FluentExperienceMomentBuilder {
+  client(fn: () => void): FluentExperienceMomentBuilder;
+  client(description: string, fn: () => void): FluentExperienceMomentBuilder;
+}
+```
+
+### Spec DSL
+
+```typescript
+function specs(feature: string, fn: () => void): void;
+function specs(fn: () => void): void;
+function rule(name: string, fn: () => void): void;
+function rule(name: string, id: string, fn: () => void): void;
+function example(name: string, id?: string): ExampleBuilder;
+function thenError(errorType: 'IllegalStateError' | 'ValidationError' | 'NotFoundError', message?: string): void;
+
+interface ExampleBuilder {
+  given<T>(data: T): GivenBuilder;
+  when<W>(data: W): WhenBuilder;
+}
+
+interface GivenBuilder {
+  and<T>(data: T): GivenBuilder;
+  when<W>(data: W): WhenBuilder;
+  then<T>(data: T): ThenBuilder;
+}
+
+interface WhenBuilder {
+  then<T>(data: T): ThenBuilder;
+  and<T>(data: T): WhenBuilder;
+}
+
+interface ThenBuilder {
+  and<T>(data: T): ThenBuilder;
+}
+```
+
+### Client spec DSL
+
+```typescript
+function describe(title: string, fn: () => void): void;
+function describe(title: string, id: string, fn: () => void): void;
+function it(title: string, id?: string): void;
+function should(title: string, id?: string): void;  // alias for it
+```
+
+### Data flow builders
+
+```typescript
+function sink(id?: string): DataSinkBuilder;
+function source(id?: string): DataSourceBuilder;
+function target(id?: string): DataTargetBuilder;
+function data(config: Data | (DataItem | DataTargetItem)[]): void;
+
+class DataSinkBuilder {
+  event(name: string): EventSinkBuilder;
+  command(name: string): CommandSinkBuilder;
+  state(name: string): StateSinkBuilder;
+}
+
+class EventSinkBuilder {
+  toStream(pattern: string): ChainableSink;
+  toIntegration(...systems: Integration[]): ChainableSink;
+  toDatabase(collection: string): ChainableSink;
+  toTopic(name: string): ChainableSink;
+}
+
+class CommandSinkBuilder {
+  withState(source: DataSourceItem): this;
+  toIntegration(system: Integration | string, messageName: string, messageType: 'command' | 'query' | 'reaction'): ChainableSink;
+  toDatabase(collection: string): ChainableSink;
+  toTopic(name: string): ChainableSink;
+  hints(hint: string): ChainableSink;
+}
+
+class StateSinkBuilder {
+  toDatabase(collection: string): ChainableSink;
+  toStream(pattern: string): ChainableSink;
+}
+
+class DataSourceBuilder {
+  state<S>(name: string): StateSourceBuilder<S>;
+}
+
+class StateSourceBuilder<S> {
+  fromProjection(name: string, idField: string): ChainableSource;
+  fromSingletonProjection(name: string): ChainableSource;
+  fromCompositeProjection(name: string, idFields: string[]): ChainableSource;
+  fromReadModel(name: string): ChainableSource;
+  fromDatabase(collection: string, query?: Record<string, unknown>): ChainableSource;
+  fromApi(endpoint: string, method?: string): ChainableSource;
+  fromIntegration(...systems: (Integration | string)[]): ChainableSource;
+}
+
+class DataTargetBuilder {
+  event(name: string): DataTargetItem;
+}
+```
 
-import { COMMANDS, exportSchemaCommandHandler } from '@auto-engineer/narrative/node';
+### Integration
+
+```typescript
+function createIntegration<T extends string>(type: T, name: string): Integration<T>;
+
+interface Integration<Type extends string> {
+  readonly type: Type;
+  readonly name: string;
+  readonly Queries?: Record<string, (...args: any[]) => Promise<any>>;
+  readonly Commands?: Record<string, (...args: any[]) => Promise<any>>;
+  readonly Reactions?: Record<string, (...args: any[]) => Promise<any>>;
+}
 ```
 
-### Entry Points
+### Scene loading and model conversion
 
-| Entry Point | Import Path | Description |
-|-------------|-------------|-------------|
-| Main | `@auto-engineer/narrative` | Core DSL and types |
-| Node | `@auto-engineer/narrative/node` | Command handlers |
+```typescript
+function getScenes(opts: GetScenesOptions): Promise<{
+  scenes: Scene[];
+  vfsFiles: string[];
+  externals: string[];
+  typings: Record<string, string[]>;
+  typeMap: Map<string, string>;
+  typesByFile: Map<string, Map<string, unknown>>;
+  givenTypesByFile: Map<string, unknown[]>;
+  toModel: () => Model;
+}>;
+
+interface GetScenesOptions {
+  vfs: IFileStore;
+  root: string;
+  pattern?: RegExp;            // default: /\.(narrative|integration)\.(ts|tsx|js|jsx|mjs|cjs)$/
+  importMap?: Record<string, unknown>;
+  fastFsScan?: boolean;
+}
+
+function modelToNarrative(model: Model): Promise<GeneratedScenes>;
+
+interface GeneratedScenes {
+  files: Array<{ path: string; code: string }>;
+}
+```
 
-### Moment Types
+### ID utilities
 
-| Type | Description | Client | Server |
-|------|-------------|--------|--------|
-| `command` | User actions that modify state | Yes | Yes |
-| `query` | Read operations | Yes | Yes |
-| `react` | Event reactions | No | Yes |
-| `experience` | UI-only behaviors | Yes | No |
+```typescript
+function addAutoIds(model: Model): Model;
+function hasAllIds(model: Model): boolean;
+```
 
-### Message Types
+### GraphQL request parsing
 
 ```typescript
-type Event<Type extends string, Data> = { type: Type; data: Data };
-type Command<Type extends string, Data> = { type: Type; data: Data };
-type State<Type extends string, Data> = { type: Type; data: Data };
+function parseGraphQlRequest(request: string): ParsedGraphQlOperation;
+function parseMomentRequest(moment: { request?: string }): ParsedGraphQlOperation | undefined;
+
+interface ParsedGraphQlOperation {
+  operationName: string;
+  args: ParsedArg[];
+}
+
+interface ParsedArg {
+  name: string;
+  tsType: string;
+  graphqlType: string;
+  nullable: boolean;
+}
 ```
 
----
+### Validation
+
+```typescript
+function validateMomentRequests(model: Model): MomentRequestValidationError[];
+
+interface MomentRequestValidationError {
+  type: string;
+  message: string;
+  sceneName: string;
+  momentName: string;
+}
+```
+
+### Message types
+
+```typescript
+type Command<T extends string, D extends Record<string, unknown>> = {
+  readonly type: T;
+  readonly data: Readonly<D>;
+  readonly kind?: 'Command';
+};
+
+type Event<T extends string, D extends Record<string, unknown>> = {
+  readonly type: T;
+  readonly data: D;
+  readonly kind?: 'Event';
+};
+
+type State<T extends string, D extends Record<string, unknown>> = {
+  readonly type: T;
+  readonly data: D;
+  readonly kind?: 'State';
+};
+
+type Query<T extends string, D extends Record<string, unknown>> = {
+  type: T;
+  data: D;
+};
+```
+
+### Key Zod schemas (`@auto-engineer/narrative/schema`)
+
+| Schema | Validates |
+|---|---|
+| `modelSchema` | Complete `Model` with scenes, messages, modules, narratives |
+| `SceneSchema` | A scene with moments |
+| `MomentSchema` | Discriminated union of command/query/react/experience moments |
+| `CommandMomentSchema` | Command moment with client/server blocks |
+| `QueryMomentSchema` | Query moment with client/server blocks |
+| `ReactMomentSchema` | Reaction moment with server block |
+| `ExperienceMomentSchema` | Experience moment with client block |
+| `MessageSchema` | Discriminated union of command/event/state/query messages |
+| `SpecSchema` | Gherkin specification with rules and examples |
+| `DataSchema` | Data configuration with sinks, sources, and targets |
+| `NarrativeSchema` | Narrative grouping scenes into an ordered flow |
+| `ModuleSchema` | Module for type ownership and file grouping |
+| `DesignSchema` | Design fields for visual representation (image assets, UI specs) |
+| `UISpecSchema` | Flat element-map UI specification |
+| `NarrativePlanningSchema` | Progressive disclosure variant for planning |
+| `SceneNamesSchema` | Scene names only (initial ideation) |
+| `MomentNamesSchema` | Scene + moment names (structure planning) |
+| `ClientServerNamesSchema` | Scene + moment + client/server descriptions |
 
 ## Architecture
 
+### File tree
+
 ```
 src/
-├── index.ts
-├── node.ts
-├── narrative.ts
-├── fluent-builder.ts
-├── schema.ts
-├── types.ts
-├── data-narrative-builders.ts
-├── loader/
-├── transformers/
-├── id/
-└── commands/
-```
-
-### Key Concepts
-
-- **Scenes**: Business capabilities containing moments
-- **Moments**: Behavioral units (command, query, react, experience)
-- **Specifications**: BDD-style Given/When/Then assertions
-- **Data Flow**: Sinks (outbound) and Sources (inbound)
-
-### Dependencies
-
-| Package | Usage |
-|---------|-------|
-| `@auto-engineer/file-store` | Virtual file system |
-| `@auto-engineer/id` | ID generation |
-| `@auto-engineer/message-bus` | Command/Event types |
-| `zod` | Schema validation |
-| `typescript` | AST parsing |
-| `graphql` | GraphQL query parsing |
+  index.ts                          Main entry, re-exports all public API
+  schema.ts                         Zod schemas and inferred types for the model
+  node.ts                           Node.js convenience re-export
+  narrative.ts                      Core DSL: scene, specs, rule, example, data
+  fluent-builder.ts                 Fluent moment builders: command, query, react, experience
+  narrative-context.ts              Mutable execution context tracking current scene/moment/spec
+  narrative-registry.ts             Global singleton registry collecting scenes
+  data-narrative-builders.ts        sink/source/target builder chains
+  types.ts                          TypeScript types: Command, Event, State, Query, Integration
+  getScenes.ts                      File discovery, compilation, caching, and model assembly
+  parse-graphql-request.ts          GraphQL request string parser
+  validate-slice-requests.ts        Model-level request validation
+  testing.ts                        Legacy testing helpers (deprecated)
+  ts-type-helpers.ts                Inline object type parsing utilities
+  slice-builder.ts                  Alternative moment builder (MomentBuilder pattern)
+  id/
+    addAutoIds.ts                   Assigns auto-generated IDs to all model nodes
+    hasAllIds.ts                    Checks whether every node has an ID
+    generators.ts                   ID generation functions
+  loader/
+    index.ts                        executeAST: TS compilation + CJS execution pipeline
+    graph.ts                        Dependency graph builder
+    resolver.ts                     Module resolution
+    runtime-cjs.ts                  CJS runtime for executing compiled modules
+    importmap.ts                    Import map creation with built-in shims
+    ts-utils.ts                     TypeScript AST utilities for type extraction
+    vfs-compiler-host.ts            Virtual filesystem compiler host
+  transformers/
+    narrative-to-model/
+      index.ts                      scenesToModel: Scene[] -> Model
+      assemble.ts                   Final model assembly (modules, narratives)
+      spec-processors.ts            Given/When/Then step processing
+      type-inference.ts             Type resolution from AST info
+      derive-modules.ts             Auto-derive module structure from source files
+      inlining.ts                   Inline type references in message fields
+      integrations.ts               Extract integration metadata from data items
+    model-to-narrative/
+      index.ts                      modelToNarrative: Model -> .narrative.ts files
+      generators/                   Code generators for imports, types, GWT, flows
+      formatting/                   Prettier formatting and type sorting
+```
+
+### Dependency table
+
+| Dependency | Role |
+|---|---|
+| `@auto-engineer/file-store` | Virtual filesystem abstraction for reading narrative files |
+| `@auto-engineer/id` | ID generation utilities |
+| `@auto-engineer/message-bus` | Message bus integration |
+| `zod` | Schema definition and runtime validation |
+| `zod-to-json-schema` | Convert Zod schemas to JSON Schema |
+| `typescript` | TypeScript compiler API for AST analysis and type extraction |
+| `graphql` / `graphql-tag` | GraphQL parsing for request definitions |
+| `prettier` | Code formatting for generated narrative files |
+| `js-sha256` | Content hashing for compilation caching |
+| `fast-glob` | File discovery |
+| `debug` | Debug logging (`auto:narrative:*` namespace) |

package/package.json

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