@auto-engineer/narrative 1.156.0 → 1.158.0

package/ketchup-plan.md

@@ -1,10 +1,20 @@
-# Ketchup Plan: Fix Scaffolder ListType Handling + node:crypto Protocol
+# Ketchup Plan: Model Schema + DSL + Bidirectional Transformers
 
 ## TODO
 
-(none)
+- [x] Burst 2b: initiator on BaseMomentSchema + .initiator() DSL method + tests [depends: none] (637390ac)
+- [x] Burst 2c: buildMoment emission for initiator + fix stream/via debt + tests [depends: 2b] (0fc29650)
+- [x] Burst 3: ModelLevelRegistry + actor()/entity() DSL + tests [depends: none] (b6fc86dd)
+- [x] Burst 4: narrative() DSL (config object) + tests [depends: 3] (251b50a2)
+- [x] Burst 5: assumptions()/requirements() 2-level dispatch + scene metadata + tests [depends: 3] (b31ab3b3)
+- [x] Burst 6: Exports + loader integration [depends: 4, 5] (7f676bfa)
+- [x] Burst 7: Fix assembleSpecs debt + wire model metadata + narrative definitions + tests [depends: 6] (55854ff5)
+- [x] Burst 8: Metadata AST builders + model-level emission + tests [depends: none] (972c70dc)
+- [x] Burst 9: Narrative block generation + metadata file wiring + tests [depends: 8] (2138e1b2)
+- [x] Burst 10: Scene-level assumptions/requirements in flow generation + tests [depends: 8] (a0512fb9)
+- [x] Burst 11: End-to-end round-trip verification tests [depends: 7, 2c, 9, 10] (11a91ac2)
 
 ## DONE
 
-- [x] Burst 1: Add isArray to getTypeName, handle ListType kind, update parseGraphQlRequest tsType wrapping — with test cases for [String!], [String!]!, [CustomType] (db71f007)
-- [x] Burst 2: Change 'crypto' to 'node:crypto' in handle.ts.ejs template
+- [x] Burst 1: ActorSchema + EntitySchema + ImpactSchema + model root fields + tests [depends: none] (ed943ed7)
+- [x] Burst 2: NarrativeSchema + SceneSchema + planning schema fields + tests [depends: 1] (2d83435b)

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.156.0",
-    "@auto-engineer/id": "1.156.0",
-    "@auto-engineer/message-bus": "1.156.0"
+    "@auto-engineer/file-store": "1.158.0",
+    "@auto-engineer/id": "1.158.0",
+    "@auto-engineer/message-bus": "1.158.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -38,7 +38,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.156.0",
+  "version": "1.158.0",
   "scripts": {
     "build": "tsx scripts/build.ts",
     "test": "vitest run --reporter=dot",

package/src/fluent-builder.specs.ts

@@ -80,3 +80,63 @@ describe('ui method', () => {
     }
   });
 });
+
+describe('initiator method', () => {
+  beforeEach(() => {
+    startScene('test-flow');
+  });
+
+  afterEach(() => {
+    clearCurrentScene();
+  });
+
+  it('sets initiator on a command moment', () => {
+    command('Submit').initiator('Operator');
+
+    const scene = getCurrentScene();
+    expect(scene!.moments[0]).toEqual({
+      type: 'command',
+      name: 'Submit',
+      initiator: 'Operator',
+      client: { specs: [] },
+      server: { description: '', specs: [], data: undefined },
+    });
+  });
+
+  it('sets initiator on a query moment', () => {
+    query('Fetch').initiator('Operator');
+
+    const scene = getCurrentScene();
+    expect(scene!.moments[0]).toEqual({
+      type: 'query',
+      name: 'Fetch',
+      initiator: 'Operator',
+      client: { specs: [] },
+      server: { description: '', specs: [], data: undefined },
+    });
+  });
+
+  it('sets initiator on a react moment', () => {
+    react('Process').initiator('Gateway');
+
+    const scene = getCurrentScene();
+    expect(scene!.moments[0]).toEqual({
+      type: 'react',
+      name: 'Process',
+      initiator: 'Gateway',
+      server: { specs: [], data: undefined },
+    });
+  });
+
+  it('sets initiator on an experience moment', () => {
+    experience('Welcome').initiator('Visitor');
+
+    const scene = getCurrentScene();
+    expect(scene!.moments[0]).toEqual({
+      type: 'experience',
+      name: 'Welcome',
+      initiator: 'Visitor',
+      client: { specs: [] },
+    });
+  });
+});

package/src/fluent-builder.ts

@@ -1,6 +1,6 @@
 import createDebug from 'debug';
 import { type ASTNode, print } from 'graphql';
-import type { CommandMoment, ExperienceMoment, QueryMoment, ReactMoment, UiBlock } from './index';
+import type { CommandMoment, Exit, ExperienceMoment, QueryMoment, ReactMoment, UiBlock } from './index';
 import {
   addMoment,
   endClientBlock,
@@ -42,6 +42,8 @@ export interface FluentCommandMomentBuilder {
   via(integration: Integration | Integration[]): FluentCommandMomentBuilder;
   retries(count: number): FluentCommandMomentBuilder;
   request(mutation: unknown): FluentCommandMomentBuilder;
+  exits(exits: Exit[]): FluentCommandMomentBuilder;
+  initiator(name: string): FluentCommandMomentBuilder;
 }
 
 export interface FluentQueryMomentBuilder {
@@ -51,6 +53,8 @@ export interface FluentQueryMomentBuilder {
   server(description: string, fn: () => void): FluentQueryMomentBuilder;
   ui(spec: UiBlock): FluentQueryMomentBuilder;
   request(query: unknown): FluentQueryMomentBuilder;
+  exits(exits: Exit[]): FluentQueryMomentBuilder;
+  initiator(name: string): FluentQueryMomentBuilder;
 }
 
 export interface FluentReactionMomentBuilder {
@@ -58,12 +62,16 @@ export interface FluentReactionMomentBuilder {
   server(description: string, fn: () => void): FluentReactionMomentBuilder;
   via(integration: Integration | Integration[]): FluentReactionMomentBuilder;
   retries(count: number): FluentReactionMomentBuilder;
+  exits(exits: Exit[]): FluentReactionMomentBuilder;
+  initiator(name: string): FluentReactionMomentBuilder;
 }
 
 export interface FluentExperienceMomentBuilder {
   client(fn: () => void): FluentExperienceMomentBuilder;
   client(description: string, fn: () => void): FluentExperienceMomentBuilder;
   ui(spec: UiBlock): FluentExperienceMomentBuilder;
+  exits(exits: Exit[]): FluentExperienceMomentBuilder;
+  initiator(name: string): FluentExperienceMomentBuilder;
 }
 
 class CommandMomentBuilderImpl implements FluentCommandMomentBuilder {
@@ -176,6 +184,17 @@ class CommandMomentBuilderImpl implements FluentCommandMomentBuilder {
     }
     return this;
   }
+
+  exits(exits: Exit[]): FluentCommandMomentBuilder {
+    debugCommand('Setting exits for moment %s: %d exits', this.moment.name, exits.length);
+    this.moment.exits = exits;
+    return this;
+  }
+
+  initiator(name: string): FluentCommandMomentBuilder {
+    this.moment.initiator = name;
+    return this;
+  }
 }
 
 class QueryMomentBuilderImpl implements FluentQueryMomentBuilder {
@@ -268,6 +287,17 @@ class QueryMomentBuilderImpl implements FluentQueryMomentBuilder {
     }
     return this;
   }
+
+  exits(exits: Exit[]): FluentQueryMomentBuilder {
+    debugQuery('Setting exits for moment %s: %d exits', this.moment.name, exits.length);
+    this.moment.exits = exits;
+    return this;
+  }
+
+  initiator(name: string): FluentQueryMomentBuilder {
+    this.moment.initiator = name;
+    return this;
+  }
 }
 
 class ReactionMomentBuilderImpl implements FluentReactionMomentBuilder {
@@ -322,6 +352,17 @@ class ReactionMomentBuilderImpl implements FluentReactionMomentBuilder {
     this.moment.additionalInstructions = `retries: ${count}`;
     return this;
   }
+
+  exits(exits: Exit[]): FluentReactionMomentBuilder {
+    debugReact('Setting exits for moment %s: %d exits', this.moment.name, exits.length);
+    this.moment.exits = exits;
+    return this;
+  }
+
+  initiator(name: string): FluentReactionMomentBuilder {
+    this.moment.initiator = name;
+    return this;
+  }
 }
 
 class ExperienceMomentBuilderImpl implements FluentExperienceMomentBuilder {
@@ -367,6 +408,17 @@ class ExperienceMomentBuilderImpl implements FluentExperienceMomentBuilder {
     this.moment.client.ui = spec;
     return this;
   }
+
+  exits(exits: Exit[]): FluentExperienceMomentBuilder {
+    debugExperience('Setting exits for moment %s: %d exits', this.moment.name, exits.length);
+    this.moment.exits = exits;
+    return this;
+  }
+
+  initiator(name: string): FluentExperienceMomentBuilder {
+    this.moment.initiator = name;
+    return this;
+  }
 }
 
 export const command = (name: string, id?: string): FluentCommandMomentBuilder => {

package/src/id/addAutoIds.ts

@@ -101,12 +101,27 @@ function processDataItems(slice: Moment): Moment {
   return modifiedMoment;
 }
 
+function processExits(slice: Moment): Moment {
+  if (!slice.exits || !Array.isArray(slice.exits) || slice.exits.length === 0) return slice;
+
+  const modifiedMoment = structuredClone(slice);
+  if (modifiedMoment.exits) {
+    modifiedMoment.exits = modifiedMoment.exits.map((exit) => {
+      const exitCopy = { ...exit };
+      ensureId(exitCopy);
+      return exitCopy;
+    });
+  }
+  return modifiedMoment;
+}
+
 function processMoment(slice: Moment): Moment {
   let sliceCopy = { ...slice };
   ensureId(sliceCopy);
   sliceCopy = processServerSpecs(sliceCopy);
   sliceCopy = processClientSpecs(sliceCopy);
   sliceCopy = processDataItems(sliceCopy);
+  sliceCopy = processExits(sliceCopy);
   return sliceCopy;
 }
 

package/src/index.ts

@@ -38,13 +38,18 @@ export { getScenes } from './getScenes';
 export { addAutoIds, hasAllIds } from './id';
 export type { ExampleBuilder, GivenBuilder, MomentTypeValueInterface, ThenBuilder, WhenBuilder } from './narrative';
 export {
+  actor,
+  assumptions,
   client,
   data,
   describe,
+  entity,
   example,
   it,
   MomentType,
+  narrative,
   request,
+  requirements,
   rule,
   scene,
   server,

package/src/loader/index.ts

@@ -1,6 +1,7 @@
 import createDebug from 'debug';
 import { integrationExportRegistry } from '../integration-export-registry';
 import { integrationRegistry } from '../integration-registry';
+import { modelLevelRegistry } from '../model-level-registry';
 import { setGivenTypesByFile } from '../narrative-context';
 import { registry } from '../narrative-registry';
 import { type BuildGraphResult, buildGraph } from './graph';
@@ -32,6 +33,7 @@ export async function executeAST(
   registry.clearAll();
   integrationRegistry.clear();
   integrationExportRegistry.clear();
+  modelLevelRegistry.clearAll();
 
   // seed with built-ins (browser-safe shims included)
   let enhanced = await createEnhancedImportMap(importMap);

package/src/model-level-registry.specs.ts

@@ -0,0 +1,217 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { command } from './fluent-builder';
+import { modelLevelRegistry } from './model-level-registry';
+import { actor, assumptions, entity, narrative, requirements } from './narrative';
+import { clearCurrentScene, getCurrentScene, startScene } from './narrative-context';
+import { registry } from './narrative-registry';
+import { scenesToModel } from './transformers/narrative-to-model';
+
+describe('ModelLevelRegistry', () => {
+  afterEach(() => {
+    modelLevelRegistry.clearAll();
+  });
+
+  it('accumulates actors via actor() DSL function', () => {
+    actor({ name: 'Operator', kind: 'person', description: 'Runs the system' });
+    actor({ name: 'Gateway', kind: 'system', description: 'Routes traffic' });
+
+    expect(modelLevelRegistry.getAll()).toEqual({
+      actors: [
+        { name: 'Operator', kind: 'person', description: 'Runs the system' },
+        { name: 'Gateway', kind: 'system', description: 'Routes traffic' },
+      ],
+      entities: [],
+      assumptions: [],
+      requirements: undefined,
+      narrativeDefinitions: [],
+    });
+  });
+
+  it('accumulates entities via entity() DSL function', () => {
+    entity({ name: 'Record', description: 'A data record', attributes: ['status'] });
+
+    expect(modelLevelRegistry.getAll()).toEqual({
+      actors: [],
+      entities: [{ name: 'Record', description: 'A data record', attributes: ['status'] }],
+      assumptions: [],
+      requirements: undefined,
+      narrativeDefinitions: [],
+    });
+  });
+
+  it('returns empty state after clearAll', () => {
+    actor({ name: 'X', kind: 'person', description: 'Y' });
+    entity({ name: 'Z', description: 'W' });
+    modelLevelRegistry.clearAll();
+
+    expect(modelLevelRegistry.getAll()).toEqual({
+      actors: [],
+      entities: [],
+      assumptions: [],
+      requirements: undefined,
+      narrativeDefinitions: [],
+    });
+  });
+
+  it('actor() throws inside scene context', () => {
+    startScene('test');
+    expect(() => actor({ name: 'X', kind: 'person', description: 'Y' })).toThrow();
+    clearCurrentScene();
+  });
+
+  it('entity() throws inside scene context', () => {
+    startScene('test');
+    expect(() => entity({ name: 'X', description: 'Y' })).toThrow();
+    clearCurrentScene();
+  });
+});
+
+describe('narrative() DSL', () => {
+  afterEach(() => {
+    modelLevelRegistry.clearAll();
+  });
+
+  it('registers narrative definition with all config fields', () => {
+    narrative('Checkout', {
+      outcome: 'Items purchased',
+      impact: 'critical',
+      actors: ['Buyer', 'Gateway'],
+      scenes: ['Add to Cart', 'Payment'],
+      assumptions: ['Gateway reachable'],
+      requirements: 'PCI compliance',
+    });
+
+    expect(modelLevelRegistry.getAll().narrativeDefinitions).toEqual([
+      {
+        name: 'Checkout',
+        outcome: 'Items purchased',
+        impact: 'critical',
+        actors: ['Buyer', 'Gateway'],
+        scenes: ['Add to Cart', 'Payment'],
+        assumptions: ['Gateway reachable'],
+        requirements: 'PCI compliance',
+      },
+    ]);
+  });
+
+  it('supports id overload', () => {
+    narrative('Setup', 'nar-1', { scenes: ['Configure'] });
+
+    expect(modelLevelRegistry.getAll().narrativeDefinitions).toEqual([
+      { name: 'Setup', id: 'nar-1', scenes: ['Configure'] },
+    ]);
+  });
+
+  it('registers minimal narrative with no optional fields', () => {
+    narrative('Simple', {});
+
+    expect(modelLevelRegistry.getAll().narrativeDefinitions).toEqual([{ name: 'Simple' }]);
+  });
+});
+
+describe('assumptions() and requirements() 2-level dispatch', () => {
+  afterEach(() => {
+    modelLevelRegistry.clearAll();
+    clearCurrentScene();
+  });
+
+  it('assumptions() at model level adds to registry', () => {
+    assumptions('System is online', 'Data is consistent');
+
+    expect(modelLevelRegistry.getAll().assumptions).toEqual(['System is online', 'Data is consistent']);
+  });
+
+  it('assumptions() inside scene adds to scene object', () => {
+    startScene('Process');
+    assumptions('Input is valid');
+
+    expect(getCurrentScene()).toEqual({
+      name: 'Process',
+      moments: [],
+      assumptions: ['Input is valid'],
+    });
+  });
+
+  it('requirements() at model level sets on registry', () => {
+    requirements('Must support multi-tenancy');
+
+    expect(modelLevelRegistry.getAll().requirements).toBe('Must support multi-tenancy');
+  });
+
+  it('requirements() inside scene sets on scene object', () => {
+    startScene('Process');
+    requirements('Must validate before processing');
+
+    expect(getCurrentScene()).toEqual({
+      name: 'Process',
+      moments: [],
+      requirements: 'Must validate before processing',
+    });
+  });
+
+  it('requirements() replaces previous value at model level', () => {
+    requirements('First');
+    requirements('Second');
+
+    expect(modelLevelRegistry.getAll().requirements).toBe('Second');
+  });
+
+  it('assumptions() accumulates across multiple calls', () => {
+    assumptions('A');
+    assumptions('B', 'C');
+
+    expect(modelLevelRegistry.getAll().assumptions).toEqual(['A', 'B', 'C']);
+  });
+});
+
+describe('DSL → scenesToModel round-trip', () => {
+  afterEach(() => {
+    modelLevelRegistry.clearAll();
+    registry.clearAll();
+    clearCurrentScene();
+  });
+
+  it('produces a Model with all metadata from DSL calls', () => {
+    actor({ name: 'Operator', kind: 'person', description: 'Runs system' });
+    entity({ name: 'Item', description: 'A thing' });
+    assumptions('System online');
+    requirements('Must be fast');
+    narrative('Flow', {
+      outcome: 'Goal met',
+      impact: 'critical',
+      actors: ['Operator'],
+      scenes: ['Step'],
+      assumptions: ['Data ready'],
+      requirements: 'Sub-second',
+    });
+
+    startScene('Step', 'n-1');
+    assumptions('Input valid');
+    requirements('Validate first');
+    command('Do').initiator('Operator');
+    const sceneObj = getCurrentScene()!;
+    registry.register(sceneObj);
+    clearCurrentScene();
+
+    const model = scenesToModel(registry.getAllScenes());
+
+    expect(model.actors).toEqual([{ name: 'Operator', kind: 'person', description: 'Runs system' }]);
+    expect(model.entities).toEqual([{ name: 'Item', description: 'A thing' }]);
+    expect(model.assumptions).toEqual(['System online']);
+    expect(model.requirements).toBe('Must be fast');
+    expect(model.narratives).toEqual([
+      {
+        name: 'Flow',
+        sceneIds: ['n-1'],
+        outcome: 'Goal met',
+        impact: 'critical',
+        actors: ['Operator'],
+        assumptions: ['Data ready'],
+        requirements: 'Sub-second',
+      },
+    ]);
+    expect(model.scenes[0].assumptions).toEqual(['Input valid']);
+    expect(model.scenes[0].requirements).toBe('Validate first');
+    expect(model.scenes[0].moments[0].initiator).toBe('Operator');
+  });
+});

package/src/model-level-registry.ts

@@ -0,0 +1,60 @@
+import type { Actor, Entity, Impact } from './schema';
+
+export type NarrativeDefinition = {
+  name: string;
+  id?: string;
+  scenes?: string[];
+  outcome?: string;
+  impact?: Impact;
+  actors?: string[];
+  assumptions?: string[];
+  requirements?: string;
+};
+
+class ModelLevelRegistry {
+  private actors: Actor[] = [];
+  private entities: Entity[] = [];
+  private assumptions: string[] = [];
+  private requirements: string | undefined = undefined;
+  private narrativeDefinitions: NarrativeDefinition[] = [];
+
+  addActor(actorDef: Actor) {
+    this.actors.push(actorDef);
+  }
+
+  addEntity(entityDef: Entity) {
+    this.entities.push(entityDef);
+  }
+
+  addAssumptions(items: string[]) {
+    this.assumptions.push(...items);
+  }
+
+  setRequirements(doc: string) {
+    this.requirements = doc;
+  }
+
+  addNarrativeDefinition(def: NarrativeDefinition) {
+    this.narrativeDefinitions.push(def);
+  }
+
+  getAll() {
+    return {
+      actors: [...this.actors],
+      entities: [...this.entities],
+      assumptions: [...this.assumptions],
+      requirements: this.requirements,
+      narrativeDefinitions: [...this.narrativeDefinitions],
+    };
+  }
+
+  clearAll() {
+    this.actors = [];
+    this.entities = [];
+    this.assumptions = [];
+    this.requirements = undefined;
+    this.narrativeDefinitions = [];
+  }
+}
+
+export const modelLevelRegistry = new ModelLevelRegistry();

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

@@ -3607,4 +3607,106 @@ scene('All Projection Types', 'ALL-PROJ', () => {
     expect(code).toContain("surface: 'route'");
     expect(code).toContain("root: 'layout-root'");
   });
+
+  it('should emit .stream(), .initiator(), and .via() on moments', async () => {
+    const model: Model = {
+      variant: 'specs',
+      scenes: [
+        {
+          name: 'Process',
+          id: 'n-1',
+          moments: [
+            {
+              type: 'command',
+              name: 'Submit',
+              stream: 'item-${itemId}',
+              initiator: 'Operator',
+              via: ['notifier'],
+              client: { specs: [] },
+              server: { description: 'Submits item', specs: [] },
+            },
+          ],
+        },
+      ],
+      messages: [],
+      integrations: [{ name: 'notifier', source: './integrations' }],
+      modules: [],
+      narratives: [],
+    };
+
+    const result = await modelToNarrative(model);
+    const code = getCode(result);
+
+    expect(code).toContain(".stream('item-${itemId}')");
+    expect(code).toContain(".initiator('Operator')");
+    expect(code).toContain('.via(Notifier)');
+  });
+
+  it('should generate metadata file with actors, entities, and narratives', async () => {
+    const model: Model = {
+      variant: 'specs',
+      scenes: [{ name: 'Step A', id: 'n-1', moments: [] }],
+      messages: [],
+      modules: [],
+      narratives: [
+        {
+          name: 'Flow',
+          sceneIds: ['n-1'],
+          outcome: 'Goal achieved',
+          impact: 'critical',
+          actors: ['Op'],
+        },
+      ],
+      actors: [{ name: 'Op', kind: 'person', description: 'Runs it' }],
+      entities: [{ name: 'Item', description: 'A thing' }],
+      assumptions: ['Online'],
+      requirements: 'Fast',
+    };
+
+    const result = await modelToNarrative(model);
+    const metadataFile = result.files.find((f) => f.path === 'model.narrative.ts');
+
+    expect(metadataFile).toEqual({
+      path: 'model.narrative.ts',
+      code: expect.stringMatching(/actor\([\s\S]*entity\([\s\S]*assumptions\([\s\S]*requirements\([\s\S]*narrative\(/),
+    });
+  });
+
+  it('should not generate metadata file when model has no metadata', async () => {
+    const model: Model = {
+      variant: 'specs',
+      scenes: [{ name: 'Simple', id: 'n-1', moments: [] }],
+      messages: [],
+      modules: [],
+      narratives: [{ name: 'Default', sceneIds: ['n-1'] }],
+    };
+
+    const result = await modelToNarrative(model);
+    const metadataPaths = result.files.filter((f) => f.path === 'model.narrative.ts');
+
+    expect(metadataPaths).toEqual([]);
+  });
+
+  it('should emit assumptions() and requirements() inside scene callbacks', async () => {
+    const model: Model = {
+      variant: 'specs',
+      scenes: [
+        {
+          name: 'Process',
+          id: 'n-1',
+          moments: [],
+          assumptions: ['Input valid'],
+          requirements: 'Must validate first',
+        },
+      ],
+      messages: [],
+      modules: [],
+      narratives: [],
+    };
+
+    const result = await modelToNarrative(model);
+    const code = getCode(result);
+
+    expect(code).toMatch(/scene\([\s\S]*assumptions\([\s\S]*requirements\(/);
+  });
 });

package/src/narrative-context.ts

@@ -87,6 +87,16 @@ export function clearCurrentScene(): void {
   context = null;
 }
 
+export function addSceneAssumptions(items: string[]): void {
+  if (!context) throw new Error('No active scene');
+  context.scene.assumptions = [...(context.scene.assumptions ?? []), ...items];
+}
+
+export function setSceneRequirements(doc: string): void {
+  if (!context) throw new Error('No active scene');
+  context.scene.requirements = doc;
+}
+
 export function getCurrentMoment(): Moment | null {
   if (!context || context.currentMomentIndex === null) return null;
   return context.scene.moments[context.currentMomentIndex] ?? null;