@sprig-and-prose/sprig-scenes 0.1.1

package/src/compiler/compile_scene_file.js

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview File wrapper for scene compilation
+ */
+
+import { readFile } from 'node:fs/promises';
+import { compileSceneFromText } from './compile_scene.js';
+
+/**
+ * @param {string} path
+ * @returns {Promise<import('../manifest/scene_manifest.js').SceneManifest>}
+ */
+export async function compileSceneFile(path) {
+  const sourceText = await readFile(path, 'utf-8');
+  return compileSceneFromText(sourceText);
+}

package/src/index.js

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Scenes library API: compileFromPath / compileFromString return SceneInstance (portal handles + derived functions).
+ */
+
+import { compileFromPath as compileFromPathImpl, compileFromString as compileFromStringImpl } from './api/SceneCompiler.js';
+import { createRuntime } from './api/SceneRuntime.js';
+import { createSceneInstance } from './api/SceneInstance.js';
+
+// Export attestation modules
+export { loadAttestations, saveAttestations } from './attestations/attestations.js';
+export { computeProjectionStatus } from './attestations/compute_status.js';
+
+/**
+ * Compile a scene from a file path. Returns a SceneInstance (Proxy).
+ * @param {string} path
+ * @returns {Promise<Proxy>}
+ */
+async function compileFromPath(path) {
+  const manifest = await compileFromPathImpl(path);
+  const runtime = createRuntime(manifest);
+  return createSceneInstance(manifest, runtime);
+}
+
+/**
+ * Compile a scene from source text. Returns a SceneInstance (Proxy).
+ * @param {string} source
+ * @returns {Proxy}
+ */
+function compileFromString(source) {
+  const manifest = compileFromStringImpl(source);
+  const runtime = createRuntime(manifest);
+  return createSceneInstance(manifest, runtime);
+}
+
+const Scenes = {
+  compileFromPath,
+  compileFromString,
+};
+
+export default Scenes;
+export { compileFromPath, compileFromString };

package/src/manifest/scene_manifest.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Scene manifest types for canonical scene compilation (TypeScript declarations).
+ * Matches JSDoc in scene_manifest.js.
+ */
+
+export type PrimitiveKind =
+  | 'string'
+  | 'integer'
+  | 'boolean'
+  | 'float'
+  | 'date'
+  | 'route';
+
+/** Uniform kind: primitive, object (named fields), or array. */
+export type Kind =
+  | { primitive: PrimitiveKind }
+  | { object: Record<string, KindRef> }
+  | { array: KindRef };
+
+/** Reference: full Kind or actor by name. */
+export type KindRef = Kind | { actor: string };
+
+/** Portal definition: declares boundary shape (read-only). */
+export interface PortalDef {
+  kind: KindRef;
+}
+
+/** Reference to a prior step (by id), a portal (by name), or another derived block (by name). */
+export type DerivedStepRef = { stepId: string } | { portal: string } | { derived: string };
+
+/** Path expression: stored as string, e.g. "ContainerRows[].item.tools[].name". */
+export type PathExpr = string;
+
+export type DerivedStep =
+  | {
+      id: string;
+      name?: string;
+      type: 'values';
+      pathExpr?: PathExpr;
+      items?: Array<{ ref: string; expand?: boolean }>;
+    }
+  | { id: string; name?: string; type: 'count'; from: DerivedStepRef }
+  | { id: string; name?: string; type: 'unique'; from: DerivedStepRef }
+  | {
+      id: string;
+      name?: string;
+      type: 'sort';
+      from: DerivedStepRef;
+      order: 'ascending' | 'descending';
+    }
+  | {
+      id: string;
+      name?: string;
+      type: 'join';
+      from: DerivedStepRef;
+      separator: string;
+    }
+  | {
+      id: string;
+      type: 'each';
+      witness: string;
+      source: { type: 'pathExpr'; value: string };
+      shape: { type: 'object'; fields: Record<string, EachShapeField> };
+    };
+
+/** Field in an each step's shape: witness path, one-resolver, or many-resolver. */
+export type EachShapeField =
+  | { type: 'witnessPath'; witness: string; path: string[] }
+  | {
+      type: 'one';
+      from: { type: 'pathExpr'; value: string };
+      by: string;
+      matches: { witness: string; path: string[] };
+    }
+  | {
+      type: 'many';
+      from: { type: 'pathExpr'; value: string };
+      by: string;
+      matches: { witness: string; path: string[] };
+      expects?: 'any' | 'some';
+    };
+
+export interface DerivedBlock {
+  steps: DerivedStep[];
+  kind?: KindRef;
+}
+
+export interface ActorDef {
+  kind: Kind;
+  identity: string[];
+}
+
+export interface SceneManifest {
+  sceneName: string;
+  actors: Record<string, ActorDef>;
+  portals: Record<string, PortalDef>;
+  derived: Record<string, DerivedBlock>;
+}

package/src/manifest/scene_manifest.js

@@ -0,0 +1,84 @@
+/**
+ * @fileoverview Scene manifest types for canonical scene compilation
+ */
+
+/**
+ * @typedef {'string' | 'integer' | 'boolean' | 'float' | 'date' | 'route'} PrimitiveKind
+ */
+
+/**
+ * Uniform kind: primitive, object (named fields), or array.
+ * @typedef {{ primitive: PrimitiveKind } | { object: Record<string, KindRef> } | { array: KindRef }} Kind
+ */
+
+/**
+ * Reference: full Kind or actor by name.
+ * @typedef {Kind | { actor: string }} KindRef
+ */
+
+/**
+ * Portal definition: declares boundary shape (read-only).
+ * @typedef {{ kind: KindRef }} PortalDef
+ */
+
+/**
+ * Reference to a prior step (by id), a portal (by name), or another derived block (by name).
+ * @typedef {{ stepId: string } | { portal: string } | { derived: string }} DerivedStepRef
+ */
+
+/**
+ * Path expression: stored as string.
+ * @typedef {string} PathExpr
+ */
+
+/**
+ * @typedef {{ id: string, name?: string, type: 'values', pathExpr?: PathExpr, items?: Array<{ ref: string, expand?: boolean }> }} DerivedStepValues
+ * @typedef {{ id: string, name?: string, type: 'count', from: DerivedStepRef }} DerivedStepCount
+ * @typedef {{ id: string, name?: string, type: 'unique', from: DerivedStepRef }} DerivedStepUnique
+ * @typedef {{ id: string, name?: string, type: 'sort', from: DerivedStepRef, order: 'ascending' | 'descending' }} DerivedStepSort
+ * @typedef {{ id: string, name?: string, type: 'join', from: DerivedStepRef, separator: string }} DerivedStepJoin
+ * @typedef {{ id: string, type: 'each', witness: string, source: { type: 'pathExpr', value: string }, shape: { type: 'object', fields: Record<string, EachShapeField> } }} DerivedStepEach
+ * @typedef {DerivedStepValues | DerivedStepCount | DerivedStepUnique | DerivedStepSort | DerivedStepJoin | DerivedStepEach} DerivedStep
+ */
+
+/**
+ * @typedef {{ type: 'witnessPath', witness: string, path: string[] } | { type: 'one', from: { type: 'pathExpr', value: string }, by: string, matches: { witness: string, path: string[] } } | { type: 'many', from: { type: 'pathExpr', value: string }, by: string, matches: { witness: string, path: string[] }, expects?: 'any' | 'some' }} EachShapeField
+ */
+
+/**
+ * @typedef {Object} DerivedBlock
+ * @property {DerivedStep[]} steps
+ * @property {KindRef} [kind]
+ */
+
+/**
+ * Location definition: declares a projection target.
+ * @typedef {Object} LocationDef
+ * @property {string} kind
+ */
+
+/**
+ * Projection expectation: declares where an actor is expected to be projected.
+ * @typedef {Object} ProjectionExpectation
+ * @property {string} location
+ * @property {'table' | 'schema' | 'dataset'} artifactType
+ * @property {string} name
+ */
+
+/**
+ * @typedef {Object} ActorDef
+ * @property {Kind} kind
+ * @property {string[]} identity
+ * @property {ProjectionExpectation[]} [expectations]
+ */
+
+/**
+ * @typedef {Object} SceneManifest
+ * @property {string} sceneName
+ * @property {Record<string, ActorDef>} actors
+ * @property {Record<string, PortalDef>} portals
+ * @property {Record<string, DerivedBlock>} derived
+ * @property {Record<string, LocationDef>} [locations]
+ */
+
+export {};

package/test/api.test.js

@@ -0,0 +1,110 @@
+/**
+ * @fileoverview Tests for Scenes library API: compileFromPath, compileFromString, SceneInstance (portal handles + derived functions).
+ */
+
+import { test } from 'node:test';
+import { strictEqual, throws } from 'node:assert/strict';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Scenes from '../src/index.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const MINIMAL_PLAYERS_PROSE = `
+scene TestScene {
+  actor Player {
+    kind {
+      id { integer }
+      name { string }
+    }
+    identity { id }
+  }
+
+  portal Players {
+    kind { [ Player ] }
+  }
+
+  derived PlayerCount {
+    count { Players }
+  }
+
+  derived PlayerNames {
+    values { Players[].name }
+    unique { values }
+    sort { from { unique } order { ascending } }
+    join { from { sort } with { ', ' } }
+  }
+}
+`;
+
+test('tutorial-style: compileFromString, set portal, call derived', () => {
+  const scene = Scenes.compileFromString(MINIMAL_PLAYERS_PROSE);
+  scene.Players.set([
+    { id: 1, name: 'John' },
+    { id: 2, name: 'Jane' },
+  ]);
+  strictEqual(scene.PlayerCount(), 2);
+  strictEqual(scene.PlayerNames(), 'Jane, John'); // sorted ascending
+});
+
+test('portal set/get: get returns last set value', () => {
+  const scene = Scenes.compileFromString(MINIMAL_PLAYERS_PROSE);
+  const data = [{ id: 1, name: 'A' }];
+  scene.Players.set(data);
+  strictEqual(scene.Players.get(), data);
+});
+
+test('portal clear: get returns undefined after clear', () => {
+  const scene = Scenes.compileFromString(MINIMAL_PLAYERS_PROSE);
+  scene.Players.set([{ id: 1, name: 'X' }]);
+  scene.Players.clear();
+  strictEqual(scene.Players.get(), undefined);
+});
+
+test('derived evaluation: PlayerCount returns number', () => {
+  const scene = Scenes.compileFromString(MINIMAL_PLAYERS_PROSE);
+  scene.Players.set([
+    { id: 1, name: 'a' },
+    { id: 2, name: 'b' },
+  ]);
+  strictEqual(scene.PlayerCount(), 2);
+});
+
+test('unknown property throws helpful message with known portals and derived', () => {
+  const scene = Scenes.compileFromString(MINIMAL_PLAYERS_PROSE);
+  throws(
+    () => {
+      scene.Playerss;
+    },
+    (err) => {
+      strictEqual(err instanceof Error, true);
+      strictEqual(err.message.includes('Unknown scene member "Playerss"'), true);
+      strictEqual(err.message.includes('Known portals:'), true);
+      strictEqual(err.message.includes('Players'), true);
+      strictEqual(err.message.includes('Known derived values:'), true);
+      strictEqual(err.message.includes('PlayerCount'), true);
+      strictEqual(err.message.includes('PlayerNames'), true);
+      return true;
+    }
+  );
+});
+
+test('derived names return callable functions', () => {
+  const scene = Scenes.compileFromString(MINIMAL_PLAYERS_PROSE);
+  strictEqual(typeof scene.PlayerCount, 'function');
+  strictEqual(typeof scene.PlayerNames, 'function');
+  scene.Players.set([]);
+  strictEqual(scene.PlayerCount(), 0);
+});
+
+test('compileFromPath: load fixture and evaluate', async () => {
+  const path = join(__dirname, 'fixtures', 'players.scene.prose');
+  const scene = await Scenes.compileFromPath(path);
+  scene.Players.set([
+    { id: 1, name: 'Alice' },
+    { id: 2, name: 'Bob' },
+  ]);
+  strictEqual(scene.PlayerCount(), 2);
+  strictEqual(scene.PlayerNames(), 'Alice, Bob');
+});

package/test/compile_scene.test.js

@@ -0,0 +1,311 @@
+/**
+ * @fileoverview Tests for scene compilation (actor, portal, derived only)
+ */
+
+import { test } from 'node:test';
+import { deepStrictEqual, strictEqual, throws } from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { compileSceneFromText } from '../src/compiler/compile_scene.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+test('compiles canonical actor scene', async () => {
+  const file = join(__dirname, '..', 'src', 'canonical', 'actor.scene.prose');
+  const sourceText = await readFile(file, 'utf-8');
+  const manifest = compileSceneFromText(sourceText);
+
+  const jsonFile = join(
+    __dirname,
+    '..',
+    'src',
+    'canonical',
+    'actor.scene.json',
+  );
+  const expectedText = await readFile(jsonFile, 'utf-8');
+  const expected = JSON.parse(expectedText);
+
+  deepStrictEqual(JSON.parse(JSON.stringify(manifest)), expected);
+});
+
+test('block comments do not affect manifest output', async () => {
+  const file = join(__dirname, '..', 'src', 'canonical', 'actor.scene.prose');
+  const baseSource = await readFile(file, 'utf-8');
+  const withComments = baseSource
+    .replace('scene LeftPanel {', 'scene LeftPanel { {* scene def *}')
+    .replace('actor Player {', 'actor Player { {* player actor *}');
+  const manifest = compileSceneFromText(withComments);
+
+  const jsonFile = join(
+    __dirname,
+    '..',
+    'src',
+    'canonical',
+    'actor.scene.json',
+  );
+  const expectedText = await readFile(jsonFile, 'utf-8');
+  const expected = JSON.parse(expectedText);
+
+  deepStrictEqual(JSON.parse(JSON.stringify(manifest)), expected);
+});
+
+test('compiles canonical actors scene', async () => {
+  const file = join(__dirname, '..', 'src', 'canonical', 'actors.scene.prose');
+  const sourceText = await readFile(file, 'utf-8');
+  const manifest = compileSceneFromText(sourceText);
+
+  const jsonFile = join(
+    __dirname,
+    '..',
+    'src',
+    'canonical',
+    'actors.scene.json',
+  );
+  const expectedText = await readFile(jsonFile, 'utf-8');
+  const expected = JSON.parse(expectedText);
+
+  deepStrictEqual(JSON.parse(JSON.stringify(manifest)), expected);
+});
+
+test('compiles canonical tools scene', async () => {
+  const file = join(__dirname, '..', 'src', 'canonical', 'tools.scene.prose');
+  const sourceText = await readFile(file, 'utf-8');
+  const manifest = compileSceneFromText(sourceText);
+
+  const jsonFile = join(
+    __dirname,
+    '..',
+    'src',
+    'canonical',
+    'tools.scene.json',
+  );
+  const expectedText = await readFile(jsonFile, 'utf-8');
+  const expected = JSON.parse(expectedText);
+
+  deepStrictEqual(JSON.parse(JSON.stringify(manifest)), expected);
+});
+
+test('tools scene: portals have array kind', async () => {
+  const file = join(__dirname, '..', 'src', 'canonical', 'tools.scene.prose');
+  const sourceText = await readFile(file, 'utf-8');
+  const manifest = compileSceneFromText(sourceText);
+
+  strictEqual(!!manifest.portals?.ContainerRows, true);
+  deepStrictEqual(manifest.portals.ContainerRows.kind, {
+    array: { actor: 'ContainerRow' },
+  });
+  strictEqual(!!manifest.portals?.AnotherToolPortal, true);
+  deepStrictEqual(manifest.portals.AnotherToolPortal.kind, {
+    array: { actor: 'Something' },
+  });
+});
+
+test('tools scene: derived RowCount has count from portal', async () => {
+  const file = join(__dirname, '..', 'src', 'canonical', 'tools.scene.prose');
+  const sourceText = await readFile(file, 'utf-8');
+  const manifest = compileSceneFromText(sourceText);
+
+  const rowCount = manifest.derived?.RowCount;
+  strictEqual(!!rowCount, true);
+  const steps = rowCount?.steps ?? [];
+  strictEqual(steps.length, 1);
+  strictEqual(steps[0]?.type, 'count');
+  deepStrictEqual(steps[0]?.from, { portal: 'ContainerRows' });
+});
+
+test('tools scene: derived ToolNames has values, unique, sort in order', async () => {
+  const file = join(__dirname, '..', 'src', 'canonical', 'tools.scene.prose');
+  const sourceText = await readFile(file, 'utf-8');
+  const manifest = compileSceneFromText(sourceText);
+
+  const toolNames = manifest.derived?.ToolNames;
+  strictEqual(!!toolNames, true);
+  const steps = toolNames?.steps ?? [];
+  strictEqual(steps.length, 3);
+  strictEqual(steps[0]?.type, 'values');
+  strictEqual(steps[1]?.type, 'unique');
+  strictEqual(steps[2]?.type, 'sort');
+  strictEqual(steps[0]?.id, 's1');
+  strictEqual(steps[1]?.id, 's2');
+  strictEqual(steps[2]?.id, 's3');
+  deepStrictEqual(steps[1]?.from, { stepId: 's1' });
+  deepStrictEqual(steps[2]?.from, { stepId: 's2' });
+  strictEqual(steps[2]?.order, 'ascending');
+});
+
+test('tools scene: derived ToolCount has count from derived ToolNames', async () => {
+  const file = join(__dirname, '..', 'src', 'canonical', 'tools.scene.prose');
+  const sourceText = await readFile(file, 'utf-8');
+  const manifest = compileSceneFromText(sourceText);
+
+  const toolCount = manifest.derived?.ToolCount;
+  strictEqual(!!toolCount, true);
+  const steps = toolCount?.steps ?? [];
+  strictEqual(steps.length, 1);
+  strictEqual(steps[0]?.type, 'count');
+  deepStrictEqual(steps[0]?.from, { derived: 'ToolNames' });
+});
+
+test('tools scene: derived ToolString1 has join step with separator', async () => {
+  const file = join(__dirname, '..', 'src', 'canonical', 'tools.scene.prose');
+  const sourceText = await readFile(file, 'utf-8');
+  const manifest = compileSceneFromText(sourceText);
+
+  const toolString = manifest.derived?.ToolString1;
+  strictEqual(!!toolString, true);
+  const joinStep = toolString?.steps?.find((s) => s.type === 'join');
+  strictEqual(!!joinStep, true);
+  strictEqual(joinStep?.separator, ', ');
+  deepStrictEqual(joinStep?.from, { derived: 'ToolNames' });
+});
+
+test('grouped actors: produces same manifest as singular', () => {
+  const grouped = `
+scene G {
+  actors {
+    A {
+      kind { id { integer } }
+      identity { id }
+    }
+  }
+}
+`;
+  const singular = `
+scene G {
+  actor A {
+    kind { id { integer } }
+    identity { id }
+  }
+}
+`;
+  const manifestGrouped = compileSceneFromText(grouped);
+  const manifestSingular = compileSceneFromText(singular);
+  deepStrictEqual(manifestGrouped.actors?.A, manifestSingular.actors?.A);
+  strictEqual(manifestGrouped.sceneName, 'G');
+  strictEqual(Object.keys(manifestGrouped.actors ?? {}).length, 1);
+  deepStrictEqual(manifestGrouped.portals, {});
+  deepStrictEqual(manifestGrouped.derived, {});
+});
+
+test('grouped portals: produces same manifest as singular', () => {
+  const grouped = `
+scene G {
+  actor R { kind { id { integer } } identity { id } }
+  portals {
+    P { kind { [ R ] } }
+  }
+}
+`;
+  const singular = `
+scene G {
+  actor R { kind { id { integer } } identity { id } }
+  portal P { kind { [ R ] } }
+}
+`;
+  const manifestGrouped = compileSceneFromText(grouped);
+  const manifestSingular = compileSceneFromText(singular);
+  deepStrictEqual(manifestGrouped.portals?.P, manifestSingular.portals?.P);
+  strictEqual(Object.keys(manifestGrouped.portals ?? {}).length, 1);
+});
+
+test('grouped derived: singular derived C is in manifest', () => {
+  const source = `
+scene G {
+  actor R { kind { id { integer } } identity { id } }
+  portal X { kind { [ R ] } }
+  derived C { count { X } }
+}
+`;
+  const manifest = compileSceneFromText(source);
+  strictEqual(!!manifest.derived?.C, true);
+  strictEqual(manifest.derived?.C?.steps?.length, 1);
+  strictEqual(manifest.derived?.C?.steps?.[0]?.type, 'count');
+  deepStrictEqual(manifest.derived?.C?.steps?.[0]?.from, { portal: 'X' });
+});
+
+test('mixed singular and grouped: actors and portals and derived appear in manifest', () => {
+  const source = `
+scene M {
+  actor X { kind { id { integer } } identity { id } }
+  actors {
+    Y { kind { id { integer } } identity { id } }
+  }
+  portal P1 { kind { [ X ] } }
+  portals {
+    P2 { kind { [ Y ] } }
+  }
+  derived D1 { count { P1 } }
+  derived D2 { count { P2 } }
+}
+`;
+  const manifest = compileSceneFromText(source);
+  strictEqual(manifest.sceneName, 'M');
+  strictEqual(!!manifest.actors?.X, true);
+  strictEqual(!!manifest.actors?.Y, true);
+  strictEqual(!!manifest.portals?.P1, true);
+  strictEqual(!!manifest.portals?.P2, true);
+  strictEqual(!!manifest.derived?.D1, true);
+  strictEqual(!!manifest.derived?.D2, true);
+});
+
+test('skills scene: derived PlayerSkills has each step with expected shape', async () => {
+  const file = join(__dirname, 'fixtures', 'skills.scene.prose');
+  const sourceText = await readFile(file, 'utf-8');
+  const manifest = compileSceneFromText(sourceText);
+
+  const playerSkills = manifest.derived?.PlayerSkills;
+  strictEqual(!!playerSkills, true);
+  strictEqual(playerSkills?.kind?.array?.actor, 'PlayerSkill');
+  const steps = playerSkills?.steps ?? [];
+  strictEqual(steps.length, 1);
+  strictEqual(steps[0]?.type, 'each');
+  strictEqual(steps[0]?.witness, 'row');
+  deepStrictEqual(steps[0]?.source, { type: 'pathExpr', value: 'RawPlayerSkills[]' });
+  const fields = steps[0]?.shape?.fields ?? {};
+  strictEqual(fields.player?.type, 'one');
+  strictEqual(fields.skill?.type, 'one');
+  strictEqual(fields.experience?.type, 'witnessPath');
+  deepStrictEqual(fields.player?.matches, { witness: 'row', path: ['playerId'] });
+  deepStrictEqual(fields.skill?.matches, { witness: 'row', path: ['skillId'] });
+  deepStrictEqual(fields.experience?.path, ['experience']);
+});
+
+test('skills-many scene: parses many block with from, matches, by', async () => {
+  const file = join(__dirname, 'fixtures', 'skills-many.scene.prose');
+  const sourceText = await readFile(file, 'utf-8');
+  const manifest = compileSceneFromText(sourceText);
+
+  const block = manifest.derived?.PlayerSkillMatches;
+  strictEqual(!!block, true);
+  const steps = block?.steps ?? [];
+  strictEqual(steps.length, 1);
+  const fields = steps[0]?.shape?.fields ?? {};
+  strictEqual(fields.skillMatches?.type, 'many');
+  deepStrictEqual(fields.skillMatches?.from, { type: 'pathExpr', value: 'Skills[]' });
+  strictEqual(fields.skillMatches?.by, 'id');
+  deepStrictEqual(fields.skillMatches?.matches, { witness: 'row', path: ['skillId'] });
+  strictEqual(fields.skillMatches?.expects, undefined);
+});
+
+test('skills-many-some scene: parses many with expects some', async () => {
+  const file = join(__dirname, 'fixtures', 'skills-many-some.scene.prose');
+  const sourceText = await readFile(file, 'utf-8');
+  const manifest = compileSceneFromText(sourceText);
+
+  const block = manifest.derived?.PlayerSkillMatchesSome;
+  strictEqual(!!block, true);
+  const fields = block?.steps?.[0]?.shape?.fields ?? {};
+  strictEqual(fields.skillMatches?.type, 'many');
+  strictEqual(fields.skillMatches?.expects, 'some');
+});
+
+test('empty scene returns empty manifest shape', () => {
+  const source = 'not a scene';
+  const manifest = compileSceneFromText(source);
+  strictEqual(manifest.sceneName, '');
+  deepStrictEqual(manifest.actors, {});
+  deepStrictEqual(manifest.portals, {});
+  deepStrictEqual(manifest.derived, {});
+});