@auto-engineer/narrative 1.157.0 → 1.158.0

package/src/narrative.ts

@@ -1,10 +1,14 @@
 import createDebug from 'debug';
 import type { DataTargetItem } from './data-narrative-builders';
+import type { NarrativeDefinition } from './model-level-registry';
+import { modelLevelRegistry } from './model-level-registry';
 import {
+  addSceneAssumptions,
   clearCurrentScene,
   endClientBlock,
   endServerBlock,
   getCurrentMoment,
+  getCurrentScene,
   popDescribe,
   pushDescribe,
   pushSpec,
@@ -14,11 +18,13 @@ import {
   recordRule,
   recordStep,
   setMomentData,
+  setSceneRequirements,
   startClientBlock,
   startScene,
   startServerBlock,
 } from './narrative-context';
 import { registry } from './narrative-registry';
+import { ActorSchema, EntitySchema, ImpactSchema } from './schema';
 import type { Data, DataItem } from './types';
 
 const debug = createDebug('auto:narrative:narrative');
@@ -234,3 +240,45 @@ export function data(config: Data | (DataItem | DataTargetItem)[]): void {
 
   setMomentData(dataConfig);
 }
+
+export function actor(config: { name: string; kind: 'person' | 'system'; description: string }): void {
+  if (getCurrentScene()) throw new Error('actor() must be called at model level, not inside a scene');
+  modelLevelRegistry.addActor(ActorSchema.parse(config));
+}
+
+export function entity(config: { name: string; description: string; attributes?: string[] }): void {
+  if (getCurrentScene()) throw new Error('entity() must be called at model level, not inside a scene');
+  modelLevelRegistry.addEntity(EntitySchema.parse(config));
+}
+
+type NarrativeConfig = Omit<NarrativeDefinition, 'name' | 'id'>;
+
+export function narrative(name: string, config: NarrativeConfig): void;
+export function narrative(name: string, id: string, config: NarrativeConfig): void;
+export function narrative(name: string, idOrConfig: string | NarrativeConfig, config?: NarrativeConfig): void {
+  const id = typeof idOrConfig === 'string' ? idOrConfig : undefined;
+  const cfg = typeof idOrConfig === 'string' ? config! : idOrConfig;
+
+  if (cfg.impact !== undefined) ImpactSchema.parse(cfg.impact);
+
+  const def: NarrativeDefinition = { name, ...cfg };
+  if (id !== undefined) def.id = id;
+
+  modelLevelRegistry.addNarrativeDefinition(def);
+}
+
+export function assumptions(...items: string[]): void {
+  if (getCurrentScene()) {
+    addSceneAssumptions(items);
+  } else {
+    modelLevelRegistry.addAssumptions(items);
+  }
+}
+
+export function requirements(doc: string): void {
+  if (getCurrentScene()) {
+    setSceneRequirements(doc);
+  } else {
+    modelLevelRegistry.setRequirements(doc);
+  }
+}

package/src/schema.specs.ts

@@ -1,6 +1,9 @@
 import { describe, expect, it } from 'vitest';
 import type {
+  Actor,
   ComponentDefinition,
+  Entity,
+  Impact,
   Narrative,
   NarrativePlanning,
   SceneClassification,
@@ -10,15 +13,19 @@ import type {
   UISpec,
 } from './schema';
 import {
+  ActorSchema,
   CommandMomentSchema,
   ComponentDefinitionSchema,
   DataSchema,
   DataTargetSchema,
   DesignSchema,
+  EntitySchema,
+  ImpactSchema,
   modelSchema,
   NarrativePlanningSchema,
   NarrativeSchema,
   QueryMomentSchema,
+  ReactMomentSchema,
   SceneClassificationSchema,
   SceneNamesOnlySchema,
   SceneRouteSchema,
@@ -57,6 +64,51 @@ describe('CommandMomentSchema', () => {
   });
 });
 
+describe('BaseMomentSchema initiator field', () => {
+  it('should accept command moment with optional initiator', () => {
+    const input = {
+      type: 'command' as const,
+      name: 'Submit',
+      initiator: 'Operator',
+      client: { specs: [] },
+      server: { description: 'Submits', specs: [] },
+    };
+    const result = CommandMomentSchema.safeParse(input);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data).toEqual(input);
+    }
+  });
+
+  it('should accept react moment with optional initiator', () => {
+    const input = {
+      type: 'react' as const,
+      name: 'Process',
+      initiator: 'Gateway',
+      server: { specs: [] },
+    };
+    const result = ReactMomentSchema.safeParse(input);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data).toEqual(input);
+    }
+  });
+
+  it('should accept moment without initiator (backward compat)', () => {
+    const input = {
+      type: 'command' as const,
+      name: 'Submit',
+      client: { specs: [] },
+      server: { description: 'Submits', specs: [] },
+    };
+    const result = CommandMomentSchema.safeParse(input);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data).toEqual(input);
+    }
+  });
+});
+
 describe('CommandMomentSchema client.ui', () => {
   it('accepts ui block in client alongside specs', () => {
     const moment = {
@@ -206,6 +258,28 @@ describe('SceneSchema scene field', () => {
       expect(result.data.scene).toBeUndefined();
     }
   });
+
+  it('should accept scene with requirements and assumptions', () => {
+    const input = {
+      name: 'Process Item',
+      moments: [],
+      requirements: 'Must validate input before processing',
+      assumptions: ['Input is well-formed JSON'],
+    };
+    const result = SceneSchema.safeParse(input);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data).toEqual(input);
+    }
+  });
+
+  it('should accept scene without requirements and assumptions (backward compat)', () => {
+    const result = SceneSchema.safeParse({ name: 'Simple', moments: [] });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data).toEqual({ name: 'Simple', moments: [] });
+    }
+  });
 });
 
 describe('NarrativeSchema', () => {
@@ -246,6 +320,31 @@ describe('NarrativeSchema', () => {
     const result = NarrativeSchema.safeParse({ name: 'Onboarding' });
     expect(result.success).toBe(false);
   });
+
+  it('should accept narrative with outcome, impact, requirements, and assumptions', () => {
+    const input = {
+      name: 'Registration',
+      sceneIds: ['n-1'],
+      outcome: 'User gains access to the system',
+      impact: 'critical' as const,
+      requirements: 'Must complete within 60 seconds',
+      assumptions: ['Email service is reachable', 'Unique constraint on username'],
+    };
+    const result = NarrativeSchema.safeParse(input);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data).toEqual(input);
+    }
+  });
+
+  it('should reject invalid impact value', () => {
+    const result = NarrativeSchema.safeParse({
+      name: 'X',
+      sceneIds: [],
+      impact: 'low',
+    });
+    expect(result.success).toBe(false);
+  });
 });
 
 describe('modelSchema narratives field', () => {
@@ -404,6 +503,44 @@ describe('NarrativePlanningSchema', () => {
 
     expect(result.success).toBe(false);
   });
+
+  it('should accept planning narrative with outcome, impact, and assumptions', () => {
+    const input = {
+      variant: 'narrative-planning' as const,
+      narratives: [
+        {
+          name: 'Setup',
+          sceneNames: ['Configure'],
+          outcome: 'System is configured',
+          impact: 'important' as const,
+          assumptions: ['Admin has credentials'],
+        },
+      ],
+      scenes: [{ name: 'Configure' }],
+    };
+    const result = NarrativePlanningSchema.safeParse(input);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data).toEqual(input);
+    }
+  });
+
+  it('should accept planning schema with model-level actors, entities, assumptions, requirements', () => {
+    const input = {
+      variant: 'narrative-planning' as const,
+      narratives: [{ name: 'Flow', sceneNames: ['Step'] }],
+      scenes: [{ name: 'Step' }],
+      actors: [{ name: 'Operator', kind: 'person' as const, description: 'Runs the system' }],
+      entities: [{ name: 'Task', description: 'A unit of work' }],
+      assumptions: ['System is online'],
+      requirements: 'Must handle concurrent access',
+    };
+    const result = NarrativePlanningSchema.safeParse(input);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data).toEqual(input);
+    }
+  });
 });
 
 describe('SceneNamesOnlySchema', () => {
@@ -771,3 +908,156 @@ describe('exported UI types', () => {
     expect(typed).toEqual(parsed);
   });
 });
+
+describe('ActorSchema', () => {
+  it('should accept a valid person actor', () => {
+    const result = ActorSchema.safeParse({
+      name: 'Operator',
+      kind: 'person',
+      description: 'Manages the system',
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data).toEqual({
+        name: 'Operator',
+        kind: 'person',
+        description: 'Manages the system',
+      });
+    }
+  });
+
+  it('should accept a valid system actor', () => {
+    const result = ActorSchema.safeParse({
+      name: 'Gateway',
+      kind: 'system',
+      description: 'Routes requests',
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data).toEqual({
+        name: 'Gateway',
+        kind: 'system',
+        description: 'Routes requests',
+      });
+    }
+  });
+
+  it('should reject invalid kind', () => {
+    const result = ActorSchema.safeParse({
+      name: 'Bot',
+      kind: 'robot',
+      description: 'Does things',
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('should reject missing required fields', () => {
+    expect(ActorSchema.safeParse({ name: 'X' }).success).toBe(false);
+    expect(ActorSchema.safeParse({ kind: 'person' }).success).toBe(false);
+    expect(ActorSchema.safeParse({ description: 'Y' }).success).toBe(false);
+  });
+
+  it('Actor type matches ActorSchema inference', () => {
+    const parsed = ActorSchema.parse({ name: 'A', kind: 'person', description: 'D' });
+    const typed: Actor = parsed;
+    expect(typed).toEqual({ name: 'A', kind: 'person', description: 'D' });
+  });
+});
+
+describe('EntitySchema', () => {
+  it('should accept entity with name and description', () => {
+    const result = EntitySchema.safeParse({
+      name: 'Item',
+      description: 'A trackable item',
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data).toEqual({
+        name: 'Item',
+        description: 'A trackable item',
+      });
+    }
+  });
+
+  it('should accept entity with optional attributes', () => {
+    const result = EntitySchema.safeParse({
+      name: 'Record',
+      description: 'A data record',
+      attributes: ['status', 'priority', 'label'],
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data).toEqual({
+        name: 'Record',
+        description: 'A data record',
+        attributes: ['status', 'priority', 'label'],
+      });
+    }
+  });
+
+  it('should reject missing required fields', () => {
+    expect(EntitySchema.safeParse({ name: 'X' }).success).toBe(false);
+    expect(EntitySchema.safeParse({ description: 'Y' }).success).toBe(false);
+  });
+
+  it('Entity type matches EntitySchema inference', () => {
+    const parsed = EntitySchema.parse({ name: 'E', description: 'D' });
+    const typed: Entity = parsed;
+    expect(typed).toEqual({ name: 'E', description: 'D' });
+  });
+});
+
+describe('ImpactSchema', () => {
+  it('should accept all valid impact levels', () => {
+    expect(ImpactSchema.safeParse('critical').success).toBe(true);
+    expect(ImpactSchema.safeParse('important').success).toBe(true);
+    expect(ImpactSchema.safeParse('nice-to-have').success).toBe(true);
+  });
+
+  it('should reject invalid impact level', () => {
+    expect(ImpactSchema.safeParse('low').success).toBe(false);
+    expect(ImpactSchema.safeParse('high').success).toBe(false);
+  });
+
+  it('Impact type matches ImpactSchema inference', () => {
+    const parsed = ImpactSchema.parse('critical');
+    const typed: Impact = parsed;
+    expect(typed).toBe('critical');
+  });
+});
+
+describe('modelSchema model-level metadata fields', () => {
+  const minimalModel = {
+    variant: 'specs' as const,
+    scenes: [],
+    messages: [],
+    modules: [],
+    narratives: [],
+  };
+
+  it('should accept model without new metadata fields (backward compat)', () => {
+    const result = modelSchema.safeParse(minimalModel);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data).toEqual(minimalModel);
+    }
+  });
+
+  it('should accept model with all metadata fields', () => {
+    const input = {
+      ...minimalModel,
+      actors: [
+        { name: 'Operator', kind: 'person' as const, description: 'Manages system' },
+        { name: 'Gateway', kind: 'system' as const, description: 'Routes requests' },
+      ],
+      entities: [{ name: 'Record', description: 'A data record', attributes: ['status', 'label'] }],
+      assumptions: ['All users are authenticated', 'System runs in UTC'],
+      requirements: '## Domain Requirements\n\nMust support multi-tenancy.',
+    };
+    const result = modelSchema.safeParse(input);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data).toEqual(input);
+    }
+  });
+});

package/src/schema.ts

@@ -34,6 +34,24 @@ const IntegrationSchema = z
   })
   .describe('External service integration configuration');
 
+const ActorSchema = z
+  .object({
+    name: z.string().describe('Actor name'),
+    kind: z.enum(['person', 'system']).describe('Whether this actor is a person or a system'),
+    description: z.string().describe('What this actor does in the domain'),
+  })
+  .describe('A person or system involved in the domain');
+
+const EntitySchema = z
+  .object({
+    name: z.string().describe('Entity name'),
+    description: z.string().describe('What this entity represents'),
+    attributes: z.array(z.string()).optional().describe('Key attributes of this entity'),
+  })
+  .describe('A domain noun — something actors interact with');
+
+const ImpactSchema = z.enum(['critical', 'important', 'nice-to-have']).describe('Priority level');
+
 // Data flow schemas for unified architecture
 export const MessageTargetSchema = z
   .object({
@@ -265,6 +283,17 @@ export const DesignSchema = z
   })
   .describe('Design fields for visual representation');
 
+export const ExitSchema = z
+  .object({
+    id: z.string().optional().describe('Optional unique identifier for the exit'),
+    label: z.string().describe('Human-readable name for this exit (e.g., "Forgot Password")'),
+    condition: z
+      .string()
+      .describe('Condition under which this exit is taken (e.g., "User clicks forgot password link")'),
+    sceneId: z.string().describe('ID of the target scene to navigate to'),
+  })
+  .describe('Conditional exit from a moment to another scene');
+
 const BaseMomentSchema = z
   .object({
     name: z.string(),
@@ -274,6 +303,8 @@ const BaseMomentSchema = z
     via: z.array(z.string()).optional().describe('Integration names used by this moment'),
     additionalInstructions: z.string().optional().describe('Additional instructions'),
     design: DesignSchema.optional().describe('Design fields for visual representation'),
+    exits: z.array(ExitSchema).optional().describe('Conditional exits from this moment to other scenes'),
+    initiator: z.string().optional().describe('Which actor initiates this moment — references actor by name'),
   })
   .describe('Base properties shared by all moment types');
 
@@ -457,6 +488,10 @@ export const NarrativeSchema = z
     actors: z.array(z.string()).optional(),
     sceneIds: z.array(z.string()).describe('Ordered scene IDs composing this narrative'),
     design: DesignSchema.optional().describe('Design fields for visual representation'),
+    outcome: z.string().optional().describe('What value this journey delivers'),
+    impact: ImpactSchema.optional().describe('Priority — drives which narratives to build first'),
+    requirements: z.string().optional().describe('Markdown requirements document (narrative level)'),
+    assumptions: z.array(z.string()).optional().describe('Journey-specific assumptions'),
   })
   .describe('Narrative grouping scenes into an ordered flow');
 
@@ -469,6 +504,8 @@ const SceneSchema = z
     sourceFile: z.string().optional(),
     scene: SceneClassificationSchema.optional(),
     design: DesignSchema.optional().describe('Design fields for visual representation'),
+    requirements: z.string().optional().describe('Markdown requirements document (scene level)'),
+    assumptions: z.array(z.string()).optional().describe('Flow-specific assumptions'),
   })
   .describe('Business scene containing related moments');
 
@@ -537,6 +574,9 @@ const NarrativePlanningNarrativeSchema = z
     description: z.string().optional(),
     actors: z.array(z.string()).optional(),
     sceneNames: z.array(z.string()).describe('Ordered scene names'),
+    outcome: z.string().optional().describe('What value this journey delivers'),
+    impact: ImpactSchema.optional().describe('Priority — drives which narratives to build first'),
+    assumptions: z.array(z.string()).optional().describe('Journey-specific assumptions'),
   })
   .describe('Narrative with scene names for planning');
 
@@ -545,6 +585,10 @@ export const NarrativePlanningSchema = z
     variant: z.literal('narrative-planning').describe('Narrative-based planning with scene names'),
     narratives: z.array(NarrativePlanningNarrativeSchema),
     scenes: z.array(SceneNamesOnlySchema),
+    actors: z.array(ActorSchema).optional().describe('People and systems involved in the domain'),
+    entities: z.array(EntitySchema).optional().describe('Domain nouns — things actors interact with'),
+    assumptions: z.array(z.string()).optional().describe('Domain-wide assumptions'),
+    requirements: z.string().optional().describe('Markdown requirements document (domain level)'),
   })
   .describe('Progressive disclosure variant for narrative-based planning');
 
@@ -582,6 +626,10 @@ export const modelSchema = z
     modules: z.array(ModuleSchema).describe('Modules for type ownership and file grouping'),
     narratives: z.array(NarrativeSchema),
     design: ModelDesignSchema.optional().describe('Design fields for visual representation'),
+    actors: z.array(ActorSchema).optional().describe('People and systems involved in the domain'),
+    entities: z.array(EntitySchema).optional().describe('Domain nouns — things actors interact with'),
+    assumptions: z.array(z.string()).optional().describe('Domain-wide assumptions'),
+    requirements: z.string().optional().describe('Markdown requirements document (domain level)'),
   })
   .describe('Complete system specification with all implementation details');
 
@@ -613,6 +661,9 @@ export {
   StepWithErrorSchema,
   UISchema,
   ComponentDefinitionSchema,
+  ActorSchema,
+  EntitySchema,
+  ImpactSchema,
 };
 
 export type Model = z.infer<typeof modelSchema>;
@@ -644,3 +695,7 @@ export type UISpec = z.infer<typeof UISpecSchema>;
 export type UI = z.infer<typeof UISchema>;
 export type ComponentDefinition = z.infer<typeof ComponentDefinitionSchema>;
 export type UiBlock = z.infer<typeof UiBlockSchema>;
+export type Exit = z.infer<typeof ExitSchema>;
+export type Actor = z.infer<typeof ActorSchema>;
+export type Entity = z.infer<typeof EntitySchema>;
+export type Impact = z.infer<typeof ImpactSchema>;

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

@@ -17,7 +17,9 @@ import type {
   OriginSchema,
 } from '../../../schema';
 import { jsonToExpr } from '../ast/emit-helpers';
+import { integrationNameToPascalCase } from '../utils/strings';
 import { buildConsolidatedGwtSpecBlock, type GWTBlock } from './gwt';
+import { buildAssumptionsCall, buildRequirementsCall } from './metadata';
 
 type CommandMoment = CommandMomentType;
 type QueryMoment = QueryMomentType;
@@ -438,6 +440,20 @@ function addUiToChain(
   return chain;
 }
 
+function addExitsToChain(
+  ts: typeof import('typescript'),
+  f: tsNS.NodeFactory,
+  chain: tsNS.Expression,
+  slice: Moment,
+): tsNS.Expression {
+  if (slice.exits !== undefined && slice.exits.length > 0) {
+    return f.createCallExpression(f.createPropertyAccessExpression(chain, f.createIdentifier('exits')), undefined, [
+      jsonToExpr(ts, f, slice.exits),
+    ]);
+  }
+  return chain;
+}
+
 function addRequestToChain(
   f: tsNS.NodeFactory,
   chain: tsNS.Expression,
@@ -758,6 +774,33 @@ function addServerToChain(
   return chain;
 }
 
+function addStreamToChain(f: tsNS.NodeFactory, chain: tsNS.Expression, slice: Moment): tsNS.Expression {
+  if (slice.stream !== undefined) {
+    return f.createCallExpression(f.createPropertyAccessExpression(chain, f.createIdentifier('stream')), undefined, [
+      f.createStringLiteral(slice.stream),
+    ]);
+  }
+  return chain;
+}
+
+function addInitiatorToChain(f: tsNS.NodeFactory, chain: tsNS.Expression, slice: Moment): tsNS.Expression {
+  if (slice.initiator !== undefined) {
+    return f.createCallExpression(f.createPropertyAccessExpression(chain, f.createIdentifier('initiator')), undefined, [
+      f.createStringLiteral(slice.initiator),
+    ]);
+  }
+  return chain;
+}
+
+function addViaToChain(f: tsNS.NodeFactory, chain: tsNS.Expression, slice: Moment): tsNS.Expression {
+  if (slice.via !== undefined && slice.via.length > 0) {
+    const identifiers = slice.via.map((name) => f.createIdentifier(integrationNameToPascalCase(name)));
+    const arg = identifiers.length === 1 ? identifiers[0] : f.createArrayLiteralExpression(identifiers);
+    return f.createCallExpression(f.createPropertyAccessExpression(chain, f.createIdentifier('via')), undefined, [arg]);
+  }
+  return chain;
+}
+
 function buildMoment(
   ts: typeof import('typescript'),
   f: tsNS.NodeFactory,
@@ -780,10 +823,14 @@ function buildMoment(
 
   let chain: tsNS.Expression = f.createCallExpression(f.createIdentifier(sliceCtor), undefined, args);
 
+  chain = addStreamToChain(f, chain, slice);
+  chain = addInitiatorToChain(f, chain, slice);
+  chain = addViaToChain(f, chain, slice);
   chain = addClientToChain(ts, f, chain, slice);
   chain = addUiToChain(ts, f, chain, slice);
   chain = addRequestToChain(f, chain, slice);
   chain = addServerToChain(ts, f, chain, slice, messages);
+  chain = addExitsToChain(ts, f, chain, slice);
 
   return f.createExpressionStatement(chain);
 }
@@ -795,7 +842,11 @@ export function buildFlowStatements(
 ): tsNS.Statement[] {
   const f = ts.factory;
 
-  const body = (flow.moments ?? []).map((sl: Moment) => buildMoment(ts, f, sl, messages));
+  const sceneMetadata: tsNS.Statement[] = [];
+  if (flow.assumptions?.length) sceneMetadata.push(buildAssumptionsCall(ts, f, flow.assumptions));
+  if (flow.requirements) sceneMetadata.push(buildRequirementsCall(f, flow.requirements));
+  const momentStatements = (flow.moments ?? []).map((sl: Moment) => buildMoment(ts, f, sl, messages));
+  const body = [...sceneMetadata, ...momentStatements];
 
   const flowArgs: tsNS.Expression[] = [f.createStringLiteral(flow.name)];
   if (flow.id !== null && flow.id !== undefined) {

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

@@ -1,17 +1,22 @@
 type BuildImportsOpts = { flowImport: string; integrationImport: string };
 
 export const ALL_FLOW_FUNCTION_NAMES = [
+  'actor',
+  'assumptions',
   'command',
   'data',
   'describe',
+  'entity',
   'example',
   'experience',
   'gql',
   'it',
-  'scene',
+  'narrative',
   'query',
   'react',
+  'requirements',
   'rule',
+  'scene',
   'sink',
   'source',
   'specs',

package/src/transformers/model-to-narrative/generators/metadata.specs.ts

@@ -0,0 +1,40 @@
+import ts from 'typescript';
+import { describe, expect, it } from 'vitest';
+import type { Model } from '../../../index';
+import { buildModelMetadataStatements } from './metadata';
+
+function printStatements(statements: ts.Statement[]): string {
+  const f = ts.factory;
+  const file = f.createSourceFile(statements, f.createToken(ts.SyntaxKind.EndOfFileToken), ts.NodeFlags.None);
+  const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });
+  return printer.printFile(file);
+}
+
+describe('buildModelMetadataStatements', () => {
+  it('generates actor, entity, assumptions, and requirements calls', () => {
+    const model = {
+      actors: [{ name: 'Operator', kind: 'person', description: 'Runs it' }],
+      entities: [{ name: 'Item', description: 'A thing', attributes: ['status'] }],
+      assumptions: ['Always online'],
+      requirements: 'Must be fast',
+    } as Model;
+
+    const statements = buildModelMetadataStatements(ts, model);
+    const code = printStatements(statements);
+
+    expect(code).toEqual(
+      'actor({ name: "Operator", kind: "person", description: "Runs it" });\n' +
+        'entity({ name: "Item", description: "A thing", attributes: ["status"] });\n' +
+        'assumptions("Always online");\n' +
+        'requirements("Must be fast");\n',
+    );
+  });
+
+  it('returns empty array when model has no metadata', () => {
+    const model = {} as Model;
+
+    const statements = buildModelMetadataStatements(ts, model);
+
+    expect(statements).toEqual([]);
+  });
+});