@maka/maka-cli 5.3.17 → 5.5.0

package/bundle/typescript/src/commands/game/sideQuest/factories/scene-seed-generator.js

@@ -0,0 +1,647 @@
+import fs from 'fs';
+import path from 'path';
+import { AI } from '../../../../tools/ai/ai.class.js';
+import { Player } from '../models/player.js';
+import { Room } from '../models/room.js';
+import { Logger } from '../utilities/logger.js';
+import { SceneSynthesizer } from './scene-factory.js';
+import { buildSkeletonPrompt, buildRoomsPrompt, buildNpcsPrompt, buildPuzzlesPrompt, buildItemsPrompt, parseJsonReply, validateSkeleton, normalizeSkeleton, assembleScene, classifyRepair, canBypassUnaided, } from './scene-chunks.js';
+// The fixer name convention and the player dossier live with the prompt
+// builders now (see scene-chunks.ts); re-exported so the existing
+// import sites (call.ts, game.ts) keep working unchanged.
+export { FIXER_NAME } from './scene-chunks.js';
+export class SceneSeedGenerator {
+    /** Fresh-skeleton pipeline attempts (structural faults promote to a new one). */
+    static maxPipelineAttempts = 2;
+    /** Per-pipeline chunk repairs before demanding a fresh skeleton. */
+    static maxRepairRounds = 3;
+    /** Attempts per individual AI call (skeleton or one detail chunk). */
+    static maxCallAttempts = 2;
+    // Per-call response budgets. Each is a fraction of a whole scene -- the
+    // point of chunking: no single completion carries everything, so scene
+    // scale is no longer bounded by the provider's output ceiling (a real
+    // session lost four of six whole-scene attempts to JSON truncated
+    // mid-string at the old fixed cap).
+    static SKELETON_TOKENS = 4000;
+    static ROOMS_TOKENS = 3000;
+    static NPCS_TOKENS = 6000;
+    static PUZZLES_TOKENS = 3000;
+    static ITEMS_TOKENS = 6000;
+    /**
+     * CHUNKED generation (see scene-chunks.ts for the shapes and prompts):
+     * one compact SKELETON pass fixes the scene's whole structure -- every
+     * cross-reference the validators check -- then small detail passes flesh
+     * out rooms, NPCs, puzzles, and items (items last: clue items bake in
+     * the puzzle passphrases). The assembled scene runs through the same
+     * validators as ever; a failure regenerates only the chunk responsible
+     * (classifyRepair) instead of throwing the whole scene away.
+     *
+     * `tier` scales scope and stakes; `previousFixerName` keeps the same
+     * job-giver identity across "continue"; `player` becomes the dossier
+     * that tailors the job to the runner's archetype and toolkit.
+     */
+    static async generate(logFilePath, tier = 1, previousFixerName, player) {
+        if (!AI.isConfigured())
+            return null;
+        const logger = Logger.getInstance(logFilePath, { children: [], render: () => { } });
+        const playerName = player?.name ?? 'Maka';
+        // Two budgets, deliberately separate: PIPELINE attempts (a fresh
+        // skeleton + full chunk set -- structural faults land here) and, per
+        // pipeline, chunk REPAIR rounds. A real generation burned its whole
+        // repair budget on two skeleton restarts and died with one round left
+        // for an items fault; skeleton restarts no longer eat repair rounds.
+        let carriedError;
+        for (let pipeline = 1; pipeline <= this.maxPipelineAttempts; pipeline++) {
+            try {
+                const skeleton = await this.requestSkeleton(tier, previousFixerName, player, logger, carriedError);
+                const details = await this.requestAllDetails(skeleton, logger);
+                let structuralFault;
+                for (let round = 0; round <= this.maxRepairRounds; round++) {
+                    const candidate = assembleScene(skeleton, details, playerName);
+                    try {
+                        await this.dryRunValidate(candidate, player);
+                        logger.write(`SceneSeedGenerator: assembled valid scene "${candidate.name}" (pipeline ${pipeline}, ${round} repair round(s))`);
+                        this.saveSeedToDisk(candidate, logFilePath, tier, skeleton);
+                        return candidate;
+                    }
+                    catch (err) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        const target = classifyRepair(message);
+                        if (target === 'skeleton' || round === this.maxRepairRounds) {
+                            structuralFault = message;
+                            logger.write(`SceneSeedGenerator: pipeline ${pipeline} needs a fresh skeleton (${target === 'skeleton' ? 'structural fault' : 'repair budget exhausted'}): ${message}`);
+                            break;
+                        }
+                        logger.write(`SceneSeedGenerator: validation failed -> repairing ${target}: ${message}`);
+                        if (target === 'rooms') {
+                            details.rooms = await this.requestChunk('rooms', buildRoomsPrompt(skeleton, message), this.ROOMS_TOKENS, logger);
+                        }
+                        else if (target === 'npcs') {
+                            details.npcs = await this.requestChunk('npcs', buildNpcsPrompt(skeleton, message), this.NPCS_TOKENS, logger);
+                        }
+                        else if (target === 'puzzles') {
+                            details.puzzles = await this.requestChunk('puzzles', buildPuzzlesPrompt(skeleton, message), this.PUZZLES_TOKENS, logger);
+                            // New passphrases invalidate the baked-in clue text.
+                            details.items = await this.requestChunk('items', buildItemsPrompt(skeleton, details.puzzles), this.ITEMS_TOKENS, logger);
+                        }
+                        else {
+                            details.items = await this.requestChunk('items', buildItemsPrompt(skeleton, details.puzzles, message), this.ITEMS_TOKENS, logger);
+                        }
+                    }
+                }
+                carriedError = structuralFault;
+            }
+            catch (err) {
+                carriedError = err instanceof Error ? err.message : String(err);
+                logger.write(`SceneSeedGenerator: pipeline ${pipeline} failed: ${carriedError}`);
+            }
+        }
+        logger.write(`SceneSeedGenerator: giving up (${carriedError ?? 'unknown'}) -- falling back to a static scene`);
+        return null;
+    }
+    /** The skeleton pass: structure only, fast-validated before any detail pass builds on it. */
+    static async requestSkeleton(tier, previousFixerName, player, logger, previousError) {
+        let lastError = previousError;
+        for (let attempt = 1; attempt <= this.maxCallAttempts; attempt++) {
+            const reply = await AI.ask(buildSkeletonPrompt(tier, previousFixerName, player, lastError), { maxTokens: this.SKELETON_TOKENS });
+            try {
+                const skeleton = parseJsonReply(reply);
+                skeleton.puzzles = skeleton.puzzles ?? [];
+                for (const note of normalizeSkeleton(skeleton)) {
+                    logger.write(`SceneSeedGenerator: ${note}`);
+                }
+                validateSkeleton(skeleton, player);
+                logger.write(`SceneSeedGenerator: skeleton "${skeleton.name}" -- ${skeleton.rooms.length} rooms, ${skeleton.npcs.length} npcs, ${skeleton.puzzles.length} puzzles, ${skeleton.items.length} items`);
+                return skeleton;
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err.message : String(err);
+                logger.write(`SceneSeedGenerator: skeleton attempt ${attempt} failed: ${lastError}`);
+                if (attempt === this.maxCallAttempts)
+                    throw err;
+            }
+        }
+        throw new Error('unreachable');
+    }
+    /** One detail chunk: prompt -> JSON, with one retry feeding the parse error back. */
+    static async requestChunk(label, prompt, maxTokens, logger) {
+        let lastError;
+        for (let attempt = 1; attempt <= this.maxCallAttempts; attempt++) {
+            const fullPrompt = lastError
+                ? `${prompt}\n\nYour previous attempt failed with this error -- fix it and try again: ${lastError}`
+                : prompt;
+            const reply = await AI.ask(fullPrompt, { maxTokens });
+            try {
+                const parsed = parseJsonReply(reply);
+                logger.write(`SceneSeedGenerator: chunk "${label}" ok (attempt ${attempt})`);
+                return parsed;
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err.message : String(err);
+                logger.write(`SceneSeedGenerator: chunk "${label}" attempt ${attempt} failed: ${lastError}`);
+                if (attempt === this.maxCallAttempts)
+                    throw err;
+            }
+        }
+        throw new Error('unreachable');
+    }
+    /**
+     * Rooms, NPCs, and puzzles are independent given the skeleton -- they
+     * run in parallel. Items runs after puzzles: each clue item's "details"
+     * must contain its puzzle's exact passphrase.
+     */
+    static async requestAllDetails(skeleton, logger) {
+        const [rooms, npcs, puzzles] = await Promise.all([
+            this.requestChunk('rooms', buildRoomsPrompt(skeleton), this.ROOMS_TOKENS, logger),
+            this.requestChunk('npcs', buildNpcsPrompt(skeleton), this.NPCS_TOKENS, logger),
+            skeleton.puzzles.length > 0
+                ? this.requestChunk('puzzles', buildPuzzlesPrompt(skeleton), this.PUZZLES_TOKENS, logger)
+                : Promise.resolve([]),
+        ]);
+        const items = await this.requestChunk('items', buildItemsPrompt(skeleton, puzzles), this.ITEMS_TOKENS, logger);
+        return { rooms, npcs, puzzles, items };
+    }
+    /**
+     * Saves a validated scene alongside that session's game log (same
+     * directory as `logFilePath`) so a run can be inspected or replayed later
+     * -- AI-generated scenes previously only existed in memory for the
+     * process that generated them.
+     */
+    static saveSeedToDisk(candidate, logFilePath, tier, skeleton) {
+        const logger = Logger.getInstance();
+        const sessionDir = path.dirname(logFilePath);
+        const seedPath = path.join(sessionDir, `scene-job-${tier}.json`);
+        try {
+            fs.mkdirSync(sessionDir, { recursive: true });
+            fs.writeFileSync(seedPath, JSON.stringify(candidate, null, 2));
+            // The skeleton rides along for post-mortems: it shows what the
+            // structure pass planned, separate from what the detail passes made
+            // of it.
+            if (skeleton) {
+                fs.writeFileSync(path.join(sessionDir, `scene-job-${tier}-skeleton.json`), JSON.stringify(skeleton, null, 2));
+            }
+            logger.write(`SceneSeedGenerator: saved generated scene to ${seedPath}`);
+        }
+        catch (err) {
+            logger.error(`SceneSeedGenerator: failed to save generated scene to ${seedPath}: ${err}`);
+        }
+    }
+    /**
+     * Runs the candidate through the exact same synthesis pipeline a real
+     * session would use, purely to surface referential-integrity errors
+     * (missing room/item/npc names) before committing to it. Discards the
+     * resulting Scene either way -- the real session re-synthesizes fresh
+     * (with AI flavor enabled) once this seed is handed off.
+     */
+    static async dryRunValidate(candidate, player) {
+        // Must run BEFORE synthesis: a room/npc/item with a missing or blank
+        // "name" doesn't fail synthesis with a useful error -- it crashes deep
+        // inside it with a raw JS TypeError ("Cannot read properties of
+        // undefined (reading 'normalize')"), found via a real generation where
+        // that opaque message became the "previous attempt failed" feedback fed
+        // back into the retry, giving the model nothing to actually act on.
+        this.validateBasicStructure(candidate);
+        const nexus = new Room({ name: 'Nexus', description: 'A featureless room where lost souls drift.', roomType: 'void' });
+        const throwawayPlayer = new Player({ playerName: candidate?.player?.name || 'Maka', startLocation: nexus });
+        // Referential-integrity errors in winCondition (bad item/toNpc/rewardItem
+        // names) are already caught by synthesis itself -- scene-factory.ts
+        // throws on those. This only checks the one semantic rule synthesis
+        // can't: the item must actually be findable, not already delivered.
+        await SceneSynthesizer.synthesizeFromJson(candidate, throwawayPlayer, false);
+        this.validateClueItems(candidate, player);
+        this.validateWinCondition(candidate, player);
+        this.validateMatrixDefense(candidate);
+        this.validateStartingItems(candidate, player);
+        this.validateBypassTypes(candidate);
+        this.validatePuzzleChain(candidate);
+        this.validateDoorKeys(candidate);
+        this.validateRewardItemPlacement(candidate);
+        this.validatePuzzlePlacement(candidate);
+    }
+    /**
+     * The one structural guarantee every other check assumes: every room,
+     * NPC, and item actually has a real, non-blank "name". Nothing about the
+     * JSON shape stops a model from emitting `"name": ""` or omitting the
+     * field outright, and synthesis doesn't validate it either -- it just
+     * uses whatever's there as a map key and crashes with an opaque error the
+     * moment something tries to look it up.
+     */
+    static validateBasicStructure(candidate) {
+        const isBlank = (name) => typeof name !== 'string' || name.trim().length === 0;
+        (candidate.rooms ?? []).forEach((room, i) => {
+            if (isBlank(room?.name)) {
+                throw new Error(`"rooms[${i}]" is missing a "name" (or it's blank) -- every room needs a real, non-empty name.`);
+            }
+        });
+        (candidate.npcs ?? []).forEach((npc, i) => {
+            if (isBlank(npc?.player?.name)) {
+                throw new Error(`"npcs[${i}].player.name" is missing (or it's blank) -- every NPC needs a real, non-empty name.`);
+            }
+        });
+        (candidate.items ?? []).forEach((item, i) => {
+            if (isBlank(item?.name)) {
+                throw new Error(`"items[${i}]" is missing a "name" (or it's blank) -- every item needs a real, non-empty name.`);
+            }
+        });
+        (candidate.puzzles ?? []).forEach((puzzle, i) => {
+            if (isBlank(puzzle?.name)) {
+                throw new Error(`"puzzles[${i}]" is missing a "name" (or it's blank) -- every puzzle needs a real, non-empty name.`);
+            }
+        });
+    }
+    /**
+     * A puzzle must belong to exactly one place: a room (via "puzzles[].room")
+     * or a door (via some "exits[].puzzle" naming it) -- see DOORS AS PUZZLES.
+     * Synthesis itself doesn't catch either failure mode: an orphaned puzzle
+     * (neither) silently never appears anywhere in the world, and a
+     * double-placed one (both) would exist as two disconnected instances of
+     * "the same" barrier -- solvable in the room without ever needing to open
+     * the door, or vice versa.
+     */
+    static validatePuzzlePlacement(candidate) {
+        const rooms = candidate.rooms ?? [];
+        const puzzles = candidate.puzzles ?? [];
+        const puzzleNames = new Set(puzzles.map(p => p.name));
+        const exitReferences = new Map();
+        for (const room of rooms) {
+            for (const exit of room.exits ?? []) {
+                if (!exit.puzzle)
+                    continue;
+                if (!puzzleNames.has(exit.puzzle)) {
+                    throw new Error(`Exit from "${room.name}" to "${exit.targetRoom}" references puzzle "${exit.puzzle}", which doesn't match any "puzzles[].name".`);
+                }
+                exitReferences.set(exit.puzzle, (exitReferences.get(exit.puzzle) ?? 0) + 1);
+            }
+        }
+        for (const puzzle of puzzles) {
+            const doorCount = exitReferences.get(puzzle.name) ?? 0;
+            if (puzzle.room && doorCount > 0) {
+                throw new Error(`Puzzle "${puzzle.name}" is placed both in room "${puzzle.room}" AND on a door (via "exits[].puzzle") -- it must be exactly one or the other. Remove one placement.`);
+            }
+            if (!puzzle.room && doorCount === 0) {
+                throw new Error(`Puzzle "${puzzle.name}" isn't placed anywhere -- set its "room", or reference it from an "exits[].puzzle".`);
+            }
+            if (doorCount > 1) {
+                throw new Error(`Puzzle "${puzzle.name}" is referenced by more than one "exits[].puzzle" -- a single puzzle can only guard one door.`);
+            }
+        }
+    }
+    /**
+     * The schema says a reward item must have neither "room" nor "heldBy" --
+     * solving the puzzle (or completing the win condition) is what's supposed
+     * to bring it into existence for the player -- but nothing ever actually
+     * enforced that. Found via a real session where a puzzle's rewardItem was
+     * ALSO "heldBy" the very NPC guarding it: solving the puzzle granted a
+     * second, phantom copy of the item while the NPC's own real one stayed
+     * put (and later dropped normally when killed) -- so the player ended up
+     * with two disconnected copies of "the same" item, and the NPC's own
+     * dialogue reflected the same confused premise (accusing the player of
+     * theft for solving a puzzle it had just dared them to solve).
+     */
+    static validateRewardItemPlacement(candidate) {
+        const itemByName = new Map((candidate.items ?? []).map(i => [i.name, i]));
+        for (const puzzle of candidate.puzzles ?? []) {
+            if (!puzzle.rewardItem)
+                continue;
+            const reward = itemByName.get(puzzle.rewardItem);
+            if (reward && (reward.room || reward.heldBy)) {
+                throw new Error(`Puzzle "${puzzle.name}"'s rewardItem "${puzzle.rewardItem}" already has "${reward.room ? 'room' : 'heldBy'}" set -- a reward item can't already exist somewhere in the world, since solving the puzzle is what's supposed to bring it into the player's possession. Remove "${reward.room ? 'room' : 'heldBy'}" from that item.`);
+            }
+            // A puzzle reward and the winCondition.item are opposite by definition
+            // (one MUST have no room/heldBy, the other MUST have one), so reusing
+            // the same item name for both is unsatisfiable no matter which way it's
+            // fixed -- caught via a real session where the model bounced between
+            // "remove room" and "not placed anywhere" across three straight
+            // attempts on the exact same item, because neither error alone said
+            // the two roles can't share an item. Named here explicitly so a retry
+            // fixes the actual problem instead of re-tripping the other rule.
+            if (candidate.winCondition && puzzle.rewardItem === candidate.winCondition.item) {
+                throw new Error(`Puzzle "${puzzle.name}"'s rewardItem and "winCondition.item" are the same item ("${puzzle.rewardItem}") -- they can't be, since a puzzle reward must have no "room"/"heldBy" while the winCondition.item must have one. Use two different items: the winCondition.item pre-placed somewhere in the world, and a separate rewardItem this puzzle grants.`);
+            }
+        }
+        const wcRewardName = candidate.winCondition?.rewardItem;
+        if (wcRewardName) {
+            const reward = itemByName.get(wcRewardName);
+            if (reward && (reward.room || reward.heldBy)) {
+                throw new Error(`Win condition rewardItem "${wcRewardName}" already has "${reward.room ? 'room' : 'heldBy'}" set -- same rule as a puzzle's rewardItem. Remove it.`);
+            }
+        }
+    }
+    /**
+     * Maps every item that has a concrete location (room, or heldBy an NPC
+     * whose startLocation gives it one) to that room's name. Shared by the
+     * reachability BFS and the win-condition checks below.
+     */
+    static buildItemLocationMap(candidate) {
+        const npcStartByName = new Map((candidate.npcs ?? []).map(n => [n.player.name, n.player.startLocation]));
+        const itemLocation = new Map();
+        for (const item of candidate.items ?? []) {
+            if (item.room) {
+                itemLocation.set(item.name, item.room);
+            }
+            else if (item.heldBy) {
+                const loc = npcStartByName.get(item.heldBy);
+                if (loc)
+                    itemLocation.set(item.name, loc);
+            }
+        }
+        return itemLocation;
+    }
+    /**
+     * Lock-and-key reachability BFS from the start room: a room becomes
+     * reachable once some already-reachable room has an unlocked exit to it,
+     * or a locked exit whose key has already been found in a reachable
+     * location. Rooms marked "reachable: false" are excluded from this
+     * traversal on purpose -- see validateDoorKeys.
+     */
+    static computeReachableRooms(candidate) {
+        const rooms = candidate.rooms ?? [];
+        const itemLocation = this.buildItemLocationMap(candidate);
+        const startRoom = rooms.find(r => r.isStartRoom)?.name;
+        const reachable = new Set();
+        if (!startRoom || !rooms.some(r => r.name === startRoom))
+            return reachable;
+        // Edges are BIDIRECTIONAL: the engine mirrors every declared exit
+        // into a shared two-way Door (Room.addExit writes both sides), so a
+        // one-sided declaration -- the chunked skeleton's house style --
+        // still connects both rooms in play. The old directed-only walk
+        // falsely stranded rooms reachable via the mirrored direction.
+        const edges = [];
+        for (const room of rooms) {
+            for (const exit of room.exits ?? []) {
+                edges.push({ a: room.name, b: exit.targetRoom, keyRequired: exit.keyRequired, puzzle: exit.puzzle });
+            }
+        }
+        reachable.add(startRoom);
+        let grew = true;
+        while (grew) {
+            grew = false;
+            for (const edge of edges) {
+                const from = reachable.has(edge.a) ? edge.a : reachable.has(edge.b) ? edge.b : undefined;
+                const to = from === edge.a ? edge.b : edge.a;
+                if (!from || reachable.has(to))
+                    continue;
+                const keyLocation = edge.keyRequired ? itemLocation.get(edge.keyRequired) : undefined;
+                // A puzzle-guarded exit (see DOORS AS PUZZLES) is always treated
+                // as eventually passable: the clue/competence rules guarantee a
+                // route, and pick/hack/cast/bluff is a real (if risky) shortcut.
+                // Only a plain "keyRequired" door needs its key traced to a
+                // reachable location first.
+                const passable = !!edge.puzzle || !edge.keyRequired || (keyLocation !== undefined && reachable.has(keyLocation));
+                if (passable) {
+                    reachable.add(to);
+                    grew = true;
+                }
+            }
+        }
+        return reachable;
+    }
+    /**
+     * Synthesis itself doesn't catch a locked door whose "keyRequired" names
+     * an item that doesn't exist, or one that's placed somewhere only
+     * reachable by first passing through that same door -- both leave the
+     * player permanently stuck with no way to unlock it (the real bug this
+     * guards against, found via a real session where a player was stonewalled
+     * behind a locked door for an entire play session). Also enforces the
+     * "reachable: false" contract (used for a fixer's inaccessible hideout,
+     * say): such a room must never connect to a normally-reachable one, in
+     * either direction, and nothing the player needs to retrieve may live
+     * inside one.
+     */
+    static validateDoorKeys(candidate) {
+        const rooms = candidate.rooms ?? [];
+        const items = candidate.items ?? [];
+        const roomByName = new Map(rooms.map(r => [r.name, r]));
+        for (const room of rooms) {
+            for (const exit of room.exits ?? []) {
+                if (!exit.keyRequired)
+                    continue;
+                const item = items.find(i => i.name === exit.keyRequired);
+                if (!item) {
+                    throw new Error(`Door from "${room.name}" to "${exit.targetRoom}" requires key "${exit.keyRequired}", which doesn't match any item in "items".`);
+                }
+                if (!item.room && !item.heldBy) {
+                    throw new Error(`Key item "${exit.keyRequired}" (for the door from "${room.name}" to "${exit.targetRoom}") has neither "room" nor "heldBy" set -- it isn't placed anywhere in the world, so it can never actually be found.`);
+                }
+                if (item.room && roomByName.get(item.room)?.reachable === false) {
+                    throw new Error(`Key item "${exit.keyRequired}" is placed in room "${item.room}", which is marked "reachable: false" -- it could never actually be retrieved.`);
+                }
+            }
+        }
+        // A "reachable: false" room (a fixer's hideout, say) must never connect
+        // to a normally-reachable one -- the engine wires doors bidirectionally
+        // regardless of which side declares the exit, so this has to check
+        // every declared exit's endpoints, not just exits declared from the
+        // unreachable room's own side.
+        for (const room of rooms) {
+            for (const exit of room.exits ?? []) {
+                const targetRoom = roomByName.get(exit.targetRoom);
+                if (!targetRoom)
+                    continue; // caught by synthesis itself
+                if ((room.reachable === false) !== (targetRoom.reachable === false)) {
+                    throw new Error(`Exit from "${room.name}" to "${exit.targetRoom}" connects a "reachable: false" room to a normally-reachable one -- this would let the player walk into (or the NPC walk out of) a room meant to be inaccessible. A "reachable: false" room must only connect to other "reachable: false" rooms, or have no exits at all.`);
+                }
+            }
+        }
+        const startRoom = rooms.find(r => r.isStartRoom)?.name;
+        if (!startRoom || !roomByName.has(startRoom))
+            return; // caught elsewhere
+        const reachable = this.computeReachableRooms(candidate);
+        const unreachable = rooms.filter(r => r.reachable !== false && !reachable.has(r.name));
+        if (unreachable.length > 0) {
+            throw new Error(`These rooms are unreachable from the start room "${startRoom}" given the locked doors and key placements: ${unreachable.map(r => r.name).join(', ')}. Every door's key must be reachable before the door that needs it (or mark the room "reachable": false if it's meant to be inaccessible, like a fixer's hideout).`);
+        }
+    }
+    /**
+     * requiresPuzzle references are structurally valid JSON either way (a
+     * bad name or a cycle won't make synthesis itself throw), so this walks
+     * each puzzle's prerequisite chain looking for a reference to a puzzle
+     * that doesn't exist or a cycle. Chains of any length are fine -- only
+     * missing references and cycles are rejected.
+     */
+    static validatePuzzleChain(candidate) {
+        const puzzles = candidate.puzzles ?? [];
+        const byName = new Map(puzzles.map(p => [p.name, p]));
+        for (const start of puzzles) {
+            const visited = new Set([start.name]);
+            let current = start;
+            while (current.requiresPuzzle) {
+                const next = byName.get(current.requiresPuzzle);
+                if (!next) {
+                    throw new Error(`Puzzle "${current.name}" requires puzzle "${current.requiresPuzzle}", which doesn't exist.`);
+                }
+                if (visited.has(next.name)) {
+                    throw new Error(`Puzzle chain starting at "${start.name}" cycles back to "${next.name}".`);
+                }
+                visited.add(next.name);
+                current = next;
+            }
+        }
+    }
+    /**
+     * Every AI-generated scene must have a completable win condition -- this
+     * is what the "continue into a new job" loop hooks into. Also guards
+     * against a win condition item that's already sitting in the target
+     * NPC's own inventory, which would make the "find and deliver it"
+     * premise nonsensical.
+     */
+    static validateWinCondition(candidate, player) {
+        const wc = candidate.winCondition;
+        if (!wc) {
+            throw new Error('Scene has no "winCondition". Every generated run needs one.');
+        }
+        const item = (candidate.items ?? []).find(i => i.name === wc.item);
+        if (!item) {
+            throw new Error(`Win condition item "${wc.item}" is not in "items".`);
+        }
+        if (!item.room && !item.heldBy) {
+            throw new Error(`Win condition item "${wc.item}" has neither "room" nor "heldBy" set -- it isn't placed anywhere in the world, so it can never actually be found.`);
+        }
+        // The payout is what the game actually pays AND what every NPC quotes
+        // -- a missing or nonsense figure breaks the promise/payment linkage
+        // this field exists for.
+        if (typeof wc.payout !== 'number' || !isFinite(wc.payout) || wc.payout <= 0) {
+            throw new Error(`"winCondition.payout" must be a positive number of nuyen (the job's agreed pay -- the engine transfers it on completion and the fixer quotes it). Got: ${JSON.stringify(wc.payout)}.`);
+        }
+        if (item.heldBy && item.heldBy === wc.toNpc) {
+            throw new Error(`Win condition item "${wc.item}" is already heldBy "${wc.toNpc}" -- it must be findable elsewhere, not already delivered.`);
+        }
+        const rooms = candidate.rooms ?? [];
+        if (item.room && rooms.find(r => r.name === item.room)?.reachable === false) {
+            throw new Error(`Win condition item "${wc.item}" is placed in room "${item.room}", which is marked "reachable: false" -- the player could never retrieve it.`);
+        }
+        // If the job-giver lives somewhere the player can never physically walk
+        // into (the fixer convention -- see buildSchemaGuide), "call" is the
+        // only way to complete a "give" condition, and "call" requires a
+        // commlink on BOTH ends.
+        if (wc.type === 'give' && wc.toNpc) {
+            const toNpcData = (candidate.npcs ?? []).find(n => n.player.name === wc.toNpc);
+            const toNpcRoom = rooms.find(r => r.name === toNpcData?.player.startLocation);
+            if (toNpcRoom?.reachable === false) {
+                const reachable = this.computeReachableRooms(candidate);
+                // Continuation drafts author no startingItems -- the dossier
+                // player's OWN kit (carried or equipped commlink) counts.
+                const ownsCommlink = !!player && (player.inventory.getAllItems().some(i => String(i.category).toLowerCase() === 'commlink') ||
+                    player.equipment.head?.commlink != null);
+                const playerHasCommlink = ownsCommlink ||
+                    (candidate.player?.startingItems ?? []).some(i => i.category === 'Commlink') ||
+                    (candidate.items ?? []).some(i => i.category === 'Commlink' && i.room && reachable.has(i.room));
+                if (!playerHasCommlink) {
+                    throw new Error(`Win condition target "${wc.toNpc}" is in a "reachable: false" room ("${toNpcRoom.name}"), so the player can only contact them via "call" -- but no Commlink-category item is available (not in "player.startingItems", and none findable in a reachable room). Give the player a way to get a commlink.`);
+                }
+                const fixerHasCommlink = (candidate.items ?? []).some(i => i.category === 'Commlink' && i.heldBy === wc.toNpc);
+                if (!fixerHasCommlink) {
+                    throw new Error(`Win condition target "${wc.toNpc}" is in a "reachable: false" room, reachable only via "call" -- but they don't hold a Commlink-category item themselves. Add one to "items" with "heldBy": "${wc.toNpc}".`);
+                }
+            }
+        }
+    }
+    /**
+     * bypassType is a closed enum the engine indexes into (puzzle.ts
+     * BYPASS_FLAVOR) -- an unvalidated value used to reach a live session
+     * and crash every "search" in that puzzle's room (the model emitted
+     * "con" for a social barrier before that type existed). The lookups are
+     * defensive now, but a bad value would still mean a barrier whose
+     * bypass route silently doesn't exist -- reject it with the exact
+     * allowed list instead.
+     */
+    static validateBypassTypes(candidate) {
+        const allowed = new Set(['lockpick', 'hack', 'spell', 'con']);
+        for (const puzzle of candidate.puzzles ?? []) {
+            if (puzzle.bypassType && !allowed.has(puzzle.bypassType)) {
+                throw new Error(`Puzzle "${puzzle.name}" has bypassType "${puzzle.bypassType}", which isn't valid -- use exactly one of "lockpick", "hack", "spell", "con" (lowercase), or omit the field for a barrier with no bypass route.`);
+            }
+        }
+    }
+    /**
+     * Mechanical teeth behind the dossier's "never duplicate their gear"
+     * rule: the prompt guidance alone was violated on its very first outing
+     * (an Adept's startingItems included "Weapon Focus Katana" verbatim, and
+     * the player watched the duplicate bounce off their occupied weapon
+     * slot). Rejects any startingItem whose name matches something the
+     * dossier player already carries or wears.
+     */
+    static validateStartingItems(candidate, player) {
+        if (!player)
+            return;
+        const owned = new Set(player.inventory.getAllItems().map(i => i.name.toLowerCase()));
+        for (const group of Object.values(player.equipment)) {
+            if (!group)
+                continue;
+            for (const item of Object.values(group)) {
+                if (item)
+                    owned.add(item.name.toLowerCase());
+            }
+        }
+        for (const starting of candidate.player?.startingItems ?? []) {
+            if (starting?.name && owned.has(starting.name.toLowerCase())) {
+                throw new Error(`"player.startingItems" includes "${starting.name}", which the runner ALREADY OWNS (see THE RUNNER dossier) -- remove it. Substitute a complementary basic they don't have (ammunition, a medkit, a tool), or simply grant fewer items.`);
+            }
+        }
+    }
+    /**
+     * A matrix-plane win-condition item must sit in a hasNode room with an
+     * ice NPC guarding it -- otherwise the whole run is a free walk: jack
+     * in, ride the grid (physical locks don't gate personas), take the
+     * file, done. Found via a real session that completed exactly that way
+     * with zero resistance. Hand-in-hand with the host-vault mechanic
+     * (matrix items stay sealed until the host is cracked -- see hack.ts /
+     * take.ts), this guarantees a datarun always has teeth.
+     */
+    static validateMatrixDefense(candidate) {
+        const wc = candidate.winCondition;
+        if (!wc)
+            return;
+        const item = (candidate.items ?? []).find(i => i.name === wc.item);
+        if (!item || item.plane !== 'matrix')
+            return;
+        if (!item.room) {
+            throw new Error(`Matrix-plane win condition item "${wc.item}" must be placed in a room (a hasNode room), not heldBy an NPC -- data lives on a host.`);
+        }
+        const room = (candidate.rooms ?? []).find(r => r.name === item.room);
+        if (!room?.hasNode) {
+            throw new Error(`Matrix-plane win condition item "${wc.item}" is in room "${item.room}", which has no "hasNode": true -- matrix files can only exist on a host. Mark that room hasNode.`);
+        }
+        const iceGuard = (candidate.npcs ?? []).some(n => n.plane === 'matrix' && n.player.startLocation === item.room);
+        if (!iceGuard) {
+            throw new Error(`Matrix-plane win condition item "${wc.item}" sits in hasNode room "${item.room}" with NO ice guarding it -- add an npc with "plane": "matrix", "startLocation": "${item.room}", and a combat block (logic 4-7). An undefended data vault makes the run a free win.`);
+        }
+    }
+    /**
+     * Enforces the "always some way to find the solution" guarantee: every
+     * puzzle must have a discoverable clue, placed in a different room. None
+     * of this is caught by synthesis (a puzzle with no clue, or an empty one,
+     * is still structurally valid), so it's checked separately and treated
+     * the same as any other validation failure -- it triggers a retry.
+     *
+     * Two patterns both count. Found via a real generation that kept getting
+     * rejected despite being genuinely solvable: a riddle whose answer is a
+     * real item's own name (e.g. "obsidian keycard", matching an actual item
+     * called "Obsidian Keycard" sitting in another room) needs no separate
+     * documentation -- finding it and seeing its name on screen already
+     * reveals the answer. A Book clue is still required for anything else.
+     */
+    static validateClueItems(candidate, player) {
+        const items = candidate.items ?? [];
+        for (const puzzle of candidate.puzzles ?? []) {
+            const requiredPhrase = (puzzle.requiredPhrase ?? '').toLowerCase();
+            const hasBookClue = items.some(item => item.category === 'Book' &&
+                item.room &&
+                item.room !== puzzle.room &&
+                item.details &&
+                item.details.trim().length > 0 &&
+                (!requiredPhrase || item.details.toLowerCase().includes(requiredPhrase)));
+            const hasNamedItemClue = requiredPhrase.length > 0 && items.some(item => item.room &&
+                item.room !== puzzle.room &&
+                item.name.toLowerCase() === requiredPhrase);
+            // Loosened against the dossier: a barrier whose bypassType matches
+            // the runner's own trained means (a lockpick door for a master
+            // locksmith) doesn't strictly need its credential written down --
+            // the skill IS the way past. Strict rule stays without a dossier.
+            if (!hasBookClue && !hasNamedItemClue && !canBypassUnaided(player, puzzle.bypassType)) {
+                throw new Error(`Puzzle "${puzzle.name}" has no discoverable clue: no Book-category item in a different room whose "details" contains the answer "${puzzle.requiredPhrase}", no item elsewhere literally named "${puzzle.requiredPhrase}", and its bypassType (${puzzle.bypassType ?? 'none'}) is not a means this runner reliably has. Every puzzle needs one of the three.`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=scene-seed-generator.js.map