@maka/maka-cli 5.4.0 → 5.6.0

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

@@ -0,0 +1,673 @@
+import { SKILL_NAMES } from '../models/player.js';
+/**
+ * CHUNKED scene generation (see SceneSeedGenerator.generate for the
+ * pipeline that drives this module). One monolithic whole-scene completion
+ * kept hitting the response token ceiling as scenes grew -- a real session
+ * lost four of six tier-2 attempts to JSON truncated mid-string -- and a
+ * single validation miss threw the entire scene away. So generation now
+ * runs in passes:
+ *
+ *   1. SKELETON: the whole scene's STRUCTURE -- rooms with exits/locks/
+ *      nodes, the NPC roster with locations, puzzle placements, every
+ *      item's name/role/location, and the win condition. Compact (one-line
+ *      concepts instead of prose), so every cross-reference the validators
+ *      check lives in one small completion.
+ *   2. DETAIL CHUNKS, each its own small completion against the fixed
+ *      skeleton: room prose; NPC voices/stats; puzzle riddles and
+ *      passphrases; item descriptions (clue items get their puzzle's exact
+ *      phrase baked into "details" -- which is why items runs AFTER
+ *      puzzles).
+ *   3. Assembly + the same validators as ever; a failure regenerates ONLY
+ *      the chunk responsible.
+ *
+ * No single completion carries the whole scene, so scene scale is no
+ * longer bounded by the provider's output budget.
+ */
+// The fixer's name is a fixed Shadowrun-lore convention, not something
+// generation ever varies (in-universe slang for an anonymous employer).
+export const FIXER_NAME = 'Mr. Johnson';
+// =========================== Player dossier ==============================
+/**
+ * A compact character sheet injected into the skeleton prompt so a job is
+ * built FOR the runner actually playing it (archetype, stats, toolkit).
+ * Returns '' when no player is available.
+ */
+export function buildPlayerDossier(player) {
+    if (!player)
+        return '';
+    const a = player;
+    const attrs = `body ${a.body}, agility ${a.agility}, reaction ${a.reaction}, strength ${a.strength}, ` +
+        `willpower ${a.willpower}, logic ${a.logic}, intuition ${a.intuition}, charisma ${a.charisma}` +
+        (a.magic > 0 ? `, magic ${a.magic}${a.adept ? ' (adept)' : ''}` : '') +
+        (a.resonance > 0 ? `, resonance ${a.resonance}` : '');
+    const topSkills = SKILL_NAMES
+        .filter(s => a.skillRating(s) > 0)
+        .sort((x, y) => a.skillRating(y) - a.skillRating(x))
+        .slice(0, 6)
+        .map(s => `${s} ${a.skillRating(s)}`)
+        .join(', ');
+    const carried = a.getCarriedWeapon();
+    const holsteredBonus = carried && !a.weaponDrawn ? carried.qualityBonus : 0;
+    const attack = a.getAttackPool() + holsteredBonus;
+    const defense = a.getDefensePool();
+    const deck = a.getAnyCyberdeck();
+    const caps = [];
+    if (a.adept) {
+        caps.push('Physical ADEPT: magic fuels their meat combat; NO spellcasting, NO astral projection -- spell formulas, grimoires, and foci are all useless to them');
+    }
+    else if (a.isAwakened()) {
+        caps.push('Awakened MAGE: casts manabolt/heal/armor innately, can astrally project ("project") and assense');
+    }
+    if (a.isTechnomancer()) {
+        caps.push('TECHNOMANCER: jacks into the Matrix with no deck (living persona)');
+    }
+    if (deck) {
+        caps.push(`Carries a cyberdeck (${deck.name}${deck.isBricked ? ', currently BRICKED' : ''}): can jack in, hack nodes, fight ice, lift matrix paydata, and crack PANs`);
+    }
+    if (a.inventory.getAllItems().some(i => String(i.category).toLowerCase() === 'drone')) {
+        caps.push('Has a surveillance drone: can scout all adjacent rooms at will');
+    }
+    if (a.charisma >= 5) {
+        caps.push(`A talker (charisma ${a.charisma}): social leverage and negotiation are their strength`);
+    }
+    if (a.logic >= 5 && !deck && !a.isTechnomancer()) {
+        caps.push(`Sharp technical mind (logic ${a.logic})`);
+    }
+    if (caps.length === 0) {
+        caps.push('No magic, no resonance, no deck, no drone -- a mundane who solves problems with gear, grit, and gunfire');
+    }
+    const gearBits = [];
+    if (carried)
+        gearBits.push(`weapon: ${carried.name}`);
+    const armor = a.getArmorValue();
+    if (armor > 0)
+        gearBits.push(`armor +${armor} soak`);
+    return `
+THE RUNNER (build this job FOR this specific character):
+- Name: ${a.name}${a.archetypeName ? ` -- archetype: ${a.archetypeName}` : ''}
+- Attributes: ${attrs}
+${topSkills ? `- Top skills: ${topSkills}` : ''}
+- Combat calibration: attack pool ~${attack}d6, defense pool ~${defense}d6${gearBits.length > 0 ? ` (${gearBits.join(', ')})` : ''}
+${caps.map(c => `- ${c}`).join('\n')}
+
+Tailoring rules:
+- Include at least one route, subplot, or payoff that rewards THIS runner's toolkit (matrix
+  content and hasNode rooms for a decker/technomancer; astral angles or Awakened opposition
+  for a mage; melee-shaped trouble for an adept; social leverage and "con"-bypass barriers
+  for a talker; recon value for a drone owner). Pick what fits this character and this
+  story -- don't bolt on every plane at once.
+- Never gate FINISHING the run behind a capability they lack: no matrix-plane winCondition
+  item unless they can already jack in (deck or resonance) or a findable Cyberdeck is placed
+  in a reachable room; no ward/"spell"-bypass-only route for someone who can't cast.
+- Don't hand them loot they can't use as a puzzle rewardItem or the winCondition rewardItem
+  (spellcasting gear for an adept, a second cyberdeck or drone for someone who already has
+  one). Useless-to-them gear may still exist as ordinary world dressing or valuables.
+- The runner ALREADY OWNS everything the dossier lists -- never duplicate any of it (their
+  deck, drone, weapon, focus, commlink) in the "starting"-role items. Round those out with
+  complementary basics instead: ammunition, a medkit, armor, tools -- or fewer items.
+- Scale opposition to the calibration pools above: rank-and-file threats should roll a few
+  dice below the runner's pools, and a centerpiece enforcer can match or slightly exceed
+  them. Don't send soft civilians at a combat monster, or elite security at a runner built
+  for talking their way through.
+`.trim();
+}
+// ============================ Prompt builders ============================
+const JSON_ONLY = `Output ONLY raw JSON -- no markdown fences, no commentary, no text before or after it.`;
+function repairNote(previousError) {
+    return previousError
+        ? `\n\nYour previous attempt failed with this error -- fix it specifically and try again: ${previousError}`
+        : '';
+}
+export function buildSkeletonPrompt(tier, previousFixerName, player, previousError) {
+    // Tier 1 is the only fresh start (the launch menu's "Generate a new
+    // Run"); every Johnson-commissioned draft is tier 2+ and the runner
+    // arrives fully equipped -- authoring "starting" items there was pure
+    // waste, since synthesis skips granting them on continuations anyway.
+    const isContinuation = tier > 1;
+    // NPC counts EXCLUDE the fixer: he's overhead (unreachable, no gameplay).
+    const scope = tier <= 1
+        ? '3 to 4 rooms, exactly 1 NPC besides the fixer, and exactly 1 puzzle'
+        : tier === 2
+            ? '4 to 6 rooms, 2 NPCs besides the fixer, and 1 to 2 puzzles'
+            : '6 to 8 rooms, 3 to 4 NPCs besides the fixer, and 2 to 3 puzzles';
+    const continuity = previousFixerName
+        ? `\nThis is a CONTINUATION of an ongoing relationship with the same fixer, "${previousFixerName}" --
+who commissioned the runner's last job and is lining up this one too. Reuse "${previousFixerName}"
+as this scene's fixer (same voice/personality); do not reintroduce them as a stranger.`
+        : '';
+    const dossier = buildPlayerDossier(player);
+    return `
+You are generating the STRUCTURE (skeleton) of a self-contained Shadowrun-flavored text
+adventure "run". This is job #${tier} in an ongoing campaign -- scale stakes accordingly.
+Prose comes later in separate passes: here, every "concept" is ONE tight sentence of intent,
+and everything else is structure. Get the STRUCTURE exactly right -- every name is a
+cross-reference other passes and the game engine will rely on verbatim.
+${continuity}
+${dossier ? `\n${dossier}\n` : ''}
+${JSON_ONLY}
+
+{
+  "name": string, // the run's title
+  "story": string, // 1-2 SHORT teaser sentences shown before play -- name the shape of the
+                    // trouble, never the objective, target names, locations, or passphrases
+                    // (those are learned by calling the fixer).
+  "completionMessage": string, // 1-2 sentences shown when the job completes
+  "rooms": [{
+    "name": string, "concept": string, "roomType"?: string,
+    "isStartRoom"?: boolean, // EXACTLY ONE room
+    "reachable"?: boolean, // false ONLY for the fixer's remote room -- see FIXER below
+    "owner"?: string, // an NPC's name, if it's their room
+    "hasNode"?: boolean, // a live Matrix host: hackable from inside the Matrix; releases the
+                          // room's maglocks AND unseals its matrix-plane files (the host is
+                          // the vault). 1-2 rooms in corp/tech locations only. Ice NPCs and
+                          // matrix-plane items belong ONLY in hasNode rooms, and any hasNode
+                          // room holding matrix items MUST have an ice NPC stationed in it.
+    "nodeAccess"?: "wireless"|"wired", // "wired" = AIR-GAPPED: only hackable by jacking in
+                          // physically inside the room. Use for at most one, most-sensitive
+                          // host; never make its meat-side route impossible.
+    "warded"?: boolean, // astral barrier: projecting mages can't enter. Use sparingly.
+    "exits": [{ "direction": "north"|"east"|"south"|"west"|"up"|"down", "targetRoom": string,
+                "keyRequired"?: string, // an items[].name with role "key"
+                "puzzle"?: string }] // a puzzles[].name guarding this door. A door puzzle
+                                      // lives ON THE DOOR ONLY: that puzzle must have NO
+                                      // "room" field of its own (setting both is the most
+                                      // common structural mistake -- don't).
+    // Doors are TWO-WAY automatically: declare each connection from ONE
+    // side only (with its keyRequired/puzzle on that one declaration) --
+    // never declare the reverse direction too.
+  }],
+  "npcs": [{
+    "name": string, "concept": string, "startLocation": string,
+    "plane"?: "meat"|"matrix"|"astral" // "matrix" = ICE guarding a hasNode room;
+                                        // "astral" = a spirit. Default meat.
+  }],
+  "puzzles": [{
+    "name": string, "concept": string, // what the barrier physically IS (a maglock, a
+                                        // keypad, a scanner, a doorman, a ward)
+    "room"?: string, // room-anchored placement -- OMIT when an exits[].puzzle references it
+    "bypassType"?: "lockpick"|"hack"|"spell"|"con", // the matching risky route: literal
+                          // lock -> "lockpick"; terminal/scanner -> "hack"; ward -> "spell";
+                          // a PERSON/voice-gate that could be talked past -> "con". Omit if
+                          // no such route. EXACTLY these lowercase strings.
+    "requiresPuzzle"?: string, // another puzzle solved FIRST (no cycles)
+    "rewardItem"?: string // an items[].name with role "reward" -- REQUIRED for room-anchored
+                           // puzzles (solving it is how the player gets that item); omit for
+                           // door puzzles (the open door is the reward)
+  }],
+  "items": [{
+    "name": string,
+    "role": "winCondition"|"reward"|"key"|"clue"|"loot"|"starting",
+    "category": string, // one of: Weapon, MeleeWeapon, RangedWeapon, Armor, BodyArmor,
+                         // ArmorClothing, Helmet, Hat, LegArmor, ArmArmor, Gloves, Commlink,
+                         // Cyberdeck, Drone, Credstick, CurrencyContainer, Key, Trinket,
+                         // Document, Datachip, Vice, Book, Tool, Clothing, Glasses, Boots,
+                         // Medical, StimPatch, SpellFormula, Grimoire, Focus, Ammunition
+    "room"?: string, "heldBy"?: string, // exactly one of these for roles winCondition/key/
+                                         // clue/loot; NEITHER for roles reward/starting
+    "plane"?: "meat"|"matrix", // "matrix" = paydata: only in a hasNode room, category
+                                // Datachip/Document. A matrix-plane winCondition item makes
+                                // the job a datarun (its room MUST have ice).
+    "forPuzzle"?: string // role "clue" only: which puzzle's passphrase this clue reveals.
+                          // EVERY puzzle needs exactly one clue item, category "Book",
+                          // placed in a DIFFERENT room than that puzzle (door puzzles: any
+                          // room). The clue's text is written in a later pass.
+                          // ${isContinuation ? 'Role "starting" is FORBIDDEN in this scene -- the runner arrives fully equipped (see dossier).' : 'Role "starting" items are the fresh runner\'s basic kit.'}
+  }],
+  "winCondition": {
+    "item": string, // the items[].name with role "winCondition" -- MUST have room or heldBy
+                     // set (never heldBy "toNpc" -- the player has to find it), and it is
+                     // the central plot object of "story"
+    "toNpc": string, // an npcs[].name -- who wants it delivered
+    "payout": number, // the job's pay in nuyen; the engine actually transfers this and the
+                       // fixer quotes it. ~2000-6000 for job #1, roughly half again more per
+                       // job after that
+    "rewardItem"?: string // optional bonus: an items[].name with role "reward"
+  }
+}
+
+FIXER: the job-giver is named EXACTLY "${FIXER_NAME}" (in-universe slang for an anonymous
+employer -- never invent another name for the role). Give him his own room marked
+"reachable": false with NO exits to reachable rooms; "call" is the only way to reach him.
+He MUST hold a Commlink-category item (role "loot", heldBy him), and the player must have a
+commlink available (${isContinuation ? 'the runner already carries their own -- see the dossier' : '"starting" role, or findable in a reachable room'}). He does NOT have to
+be winCondition.toNpc -- a different on-the-ground contact is often the better story; any
+such contact in an unreachable room needs a commlink of their own too.
+
+Hard structural rules (validated mechanically -- a violation is rejected):
+- Every exits[].targetRoom, npcs[].startLocation, items[].room name a real rooms[].name;
+  every items[].heldBy names a real npcs[].name; every exits[].puzzle names a real
+  puzzles[].name; every keyRequired names a real items[].name with role "key".
+- Exactly one room has isStartRoom true. Never lock the start room's only exits behind keys
+  placed beyond them: every key must be reachable WITHOUT passing through the door it opens.
+- A "reachable": false room never connects to a reachable one, and nothing the player must
+  retrieve (winCondition item, keys, clues) is ever placed in one.
+- Each puzzle is placed EXACTLY one way: its own "room", or exactly one exits[].puzzle
+  reference. Each puzzle has exactly one "clue"-role Book item (forPuzzle set) in a
+  DIFFERENT room -- EXCEPT when the puzzle's bypassType matches a skill the runner's
+  dossier shows real strength in (a lockpick barrier for a master locksmith, a con
+  barrier for a silver-tongued face): their skill IS the way past, and the clue may be
+  omitted. When in doubt, include the clue. requiresPuzzle chains never cycle.
+- The winCondition item must not be heldBy winCondition.toNpc. If a matrix-plane item is the
+  winCondition item, its room has hasNode true AND a "matrix"-plane NPC stationed there.
+- ${isContinuation
+        ? 'ZERO "starting"-role items -- the runner arrives with everything they own. 4-6'
+        : '3-5 "starting"-role items (basics the runner doesn\'t already own -- see the dossier), 4-6'}
+  "loot"-role world items, one "clue" per puzzle.
+
+Scope: ${scope}. Gritty noir Shadowrun tone: a fixer, a job, a debt, a betrayal -- and a
+fresh premise, not a generic "corp blackmail vault" rerun.${repairNote(previousError)}
+`.trim();
+}
+/** Shared context header for the detail passes: the fixed skeleton. */
+function skeletonContext(skeleton) {
+    return `The scene's FIXED skeleton (all names are final -- reference them EXACTLY, never invent new ones):
+${JSON.stringify(skeleton, null, 1)}`;
+}
+export function buildRoomsPrompt(skeleton, previousError) {
+    return `
+You are writing the room descriptions for a Shadowrun text adventure.
+
+${skeletonContext(skeleton)}
+
+For EVERY room in the skeleton, write evocative 2-3 sentence prose expanding its "concept" --
+gritty cyberpunk noir, concrete sensory detail, no mechanics talk and no spoilers (never
+reveal passphrases, hidden items, or plot twists in a room description).
+
+${JSON_ONLY}
+[ { "name": string, "description": string, "roomType": string } ]
+One entry per skeleton room, "name" copied exactly.${repairNote(previousError)}
+`.trim();
+}
+export function buildNpcsPrompt(skeleton, previousError) {
+    return `
+You are writing the characters for a Shadowrun text adventure.
+
+${skeletonContext(skeleton)}
+
+For EVERY npc in the skeleton, expand its "concept":
+- "description": private GM notes on personality/motives (never shown verbatim to the player).
+- "dialogue": 2-4 short in-character lines. For "${FIXER_NAME}" (the fixer) this is the REAL
+  briefing -- the objective (the winCondition item), where to start looking, the stakes, and
+  the exact payout figure from the skeleton (the engine pays exactly that number). When
+  referring to places, use EXACT room names from the skeleton -- never invent locations.
+- "combat": OPTIONAL attribute block -- omit for anyone who'd never fight. Each attribute
+  1-8 (soft civilian 1-2, street-level 3-4, hardened enforcer 5-6, elite 7-8):
+  { "body", "agility", "reaction", "combatSkill", "strength"?, "willpower"?, "logic"?,
+    "intuition"?, "charisma"?, "magic"?, "resonance"?, "adept"?,
+    "skills"?: { "firearms"?, "blades"?, "unarmed"?, "sneaking"?, "perception"?, "hacking"?,
+                 "locksmith"?, "negotiation"?, "con"?, "intimidation"?, "assensing"? } }
+  "magic" 3-6 ONLY for a genuinely Awakened concept; "plane":"matrix" ice fights with
+  logic 4-7; give combat blocks to anyone the story expects in a firefight. "skills" is
+  optional flavor for defined concepts (a sharpshooter's "firearms": 6).
+
+${JSON_ONLY}
+[ { "name": string, "description": string, "dialogue": string[], "combat"?: { ... } } ]
+One entry per skeleton npc, "name" copied exactly.${repairNote(previousError)}
+`.trim();
+}
+export function buildPuzzlesPrompt(skeleton, previousError) {
+    if (skeleton.puzzles.length === 0)
+        return '';
+    return `
+You are writing the barriers (puzzles) for a Shadowrun text adventure.
+
+${skeletonContext(skeleton)}
+
+For EVERY puzzle in the skeleton, expand its "concept" (what the barrier physically is --
+that's fixed, as is its bypassType):
+- "riddle": what the player sees on approaching it, shown verbatim -- PLAIN and concrete,
+  never a cryptic riddle-poem. Start with "You see" (or similar), name the barrier, then
+  what it demands (a code, a phrase, a name), the way an NPC would describe it. Never state
+  the credential itself.
+- "requiredPhrase": the exact credential -- ALL LOWERCASE, 2-5 plain words, no punctuation.
+  A concrete literal thing (a code, a passphrase, a name), never wordplay.
+- "successMessage" / "failureMessage": one sentence each, in-fiction.
+- "lockedMessage": only for puzzles with "requiresPuzzle" -- what the player sees trying it
+  too early, hinting at the prerequisite without naming mechanics.
+
+${JSON_ONLY}
+[ { "name": string, "riddle": string, "requiredPhrase": string, "successMessage": string,
+    "failureMessage": string, "lockedMessage"?: string } ]
+One entry per skeleton puzzle, "name" copied exactly.${repairNote(previousError)}
+`.trim();
+}
+export function buildItemsPrompt(skeleton, puzzles, previousError) {
+    const clueSpecs = skeleton.items
+        .filter(i => i.role === 'clue' && i.forPuzzle)
+        .map(i => {
+        const phrase = puzzles.find(p => p.name === i.forPuzzle)?.requiredPhrase;
+        return `- "${i.name}" is the clue for puzzle "${i.forPuzzle}": its "details" text MUST contain the exact phrase "${phrase ?? 'UNKNOWN'}" verbatim (a diary entry, scrawled note, or manual that gives it away once read).`;
+    })
+        .join('\n');
+    return `
+You are writing the items for a Shadowrun text adventure.
+
+${skeletonContext(skeleton)}
+
+For EVERY item in the skeleton, expand it into a full item ("name" and "category" are fixed):
+- "description": one sentence of always-visible flavor.
+- "details": deeper text shown on close examination or reading. CLUE ITEMS (below) put
+  their puzzle's credential HERE -- never in "description".
+- "size": "Tiny"|"Small"|"Medium"|"Large"|"VeryLarge"; "rating": "Common"|"Standard"|"Rare"|
+  "Legendary"|"MilitaryGrade" (rating scales combat/heal/deck power -- reserve Rare+ for
+  earned rewards); "shape"/"color"/"texture": short literals; "weight": realistic kilograms
+  (0.05 chip, ~2 pistol, ~4 armor); "currencyAmount" only for Credstick/CurrencyContainer.
+
+Clue requirements (mechanically validated -- the exact phrase must appear in "details"):
+${clueSpecs || '- (no clue items in this scene)'}
+
+${JSON_ONLY}
+[ { "name": string, "description": string, "size": string, "category": string,
+    "shape": string, "color": string, "texture": string, "rating": string, "weight": number,
+    "currencyAmount"?: number, "details"?: string, "transferable"?: boolean } ]
+One entry per skeleton item, "name" and "category" copied exactly.${repairNote(previousError)}
+`.trim();
+}
+// ========================= Parse / validate / assemble ====================
+/**
+ * Whether THIS runner can reliably work a barrier of the given bypassType
+ * with their own hands -- no written-down credential required. This is
+ * what loosens the "every puzzle needs a discoverable clue" rule when the
+ * scene is generated against a dossier: a lockpick maglock in a scene
+ * built for a master locksmith doesn't need its code lying in a book --
+ * the pick IS their route. Deliberately conservative: EXPLICIT skill
+ * ratings only (the combatSkill fallback would let any bruiser "qualify"
+ * as a hacker), threshold 3 (trained professional), and with no dossier
+ * at all the strict clue rule stays.
+ */
+export function canBypassUnaided(player, bypassType) {
+    if (!player || !bypassType)
+        return false;
+    const rated = (skill) => player.skills[skill] ?? 0;
+    switch (bypassType) {
+        case 'lockpick': return rated('locksmith') >= 3;
+        case 'hack': return rated('hacking') >= 3 || player.isTechnomancer() || !!player.getAnyCyberdeck();
+        case 'spell': return player.isAwakened() && !player.adept;
+        case 'con': return rated('con') >= 3 || player.charisma >= 5;
+        default: return false;
+    }
+}
+/** Strips accidental markdown fences and parses; throws with a useful message. */
+export function parseJsonReply(reply) {
+    const cleaned = reply.replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/i, '');
+    return JSON.parse(cleaned);
+}
+/**
+ * Fast structural checks on the skeleton BEFORE any detail pass spends
+ * tokens building on it. Deeper semantics (reachability, clue coverage,
+ * matrix defense...) are still enforced by the assembled-scene validators.
+ */
+export function validateSkeleton(skeleton, player) {
+    const fail = (msg) => { throw new Error(`Skeleton invalid: ${msg}`); };
+    if (!Array.isArray(skeleton?.rooms) || skeleton.rooms.length === 0)
+        fail('no rooms.');
+    if (!Array.isArray(skeleton?.npcs) || skeleton.npcs.length === 0)
+        fail('no npcs.');
+    if (!Array.isArray(skeleton?.items))
+        fail('no items array.');
+    if (!skeleton.winCondition?.item || !skeleton.winCondition?.toNpc)
+        fail('winCondition needs "item" and "toNpc".');
+    if (typeof skeleton.winCondition.payout !== 'number' || skeleton.winCondition.payout <= 0)
+        fail('winCondition.payout must be a positive number.');
+    const roomNames = new Set(skeleton.rooms.map(r => r.name));
+    const npcNames = new Set(skeleton.npcs.map(n => n.name));
+    const itemNames = new Set(skeleton.items.map(i => i.name));
+    const puzzleNames = new Set((skeleton.puzzles ?? []).map(p => p.name));
+    const startRooms = skeleton.rooms.filter(r => r.isStartRoom);
+    if (startRooms.length !== 1)
+        fail(`exactly one room must have "isStartRoom": true (found ${startRooms.length}).`);
+    const doorRefs = new Map();
+    for (const room of skeleton.rooms) {
+        for (const exit of room.exits ?? []) {
+            if (!roomNames.has(exit.targetRoom))
+                fail(`exit from "${room.name}" targets unknown room "${exit.targetRoom}".`);
+            if (exit.puzzle) {
+                if (!puzzleNames.has(exit.puzzle))
+                    fail(`exit from "${room.name}" references unknown puzzle "${exit.puzzle}".`);
+                doorRefs.set(exit.puzzle, (doorRefs.get(exit.puzzle) ?? 0) + 1);
+            }
+            if (exit.keyRequired && !itemNames.has(exit.keyRequired))
+                fail(`exit from "${room.name}" requires unknown key item "${exit.keyRequired}".`);
+        }
+    }
+    for (const npc of skeleton.npcs) {
+        if (!roomNames.has(npc.startLocation))
+            fail(`npc "${npc.name}" starts in unknown room "${npc.startLocation}".`);
+    }
+    for (const item of skeleton.items) {
+        if (item.room && !roomNames.has(item.room))
+            fail(`item "${item.name}" placed in unknown room "${item.room}".`);
+        if (item.heldBy && !npcNames.has(item.heldBy))
+            fail(`item "${item.name}" heldBy unknown npc "${item.heldBy}".`);
+        if (item.forPuzzle && !puzzleNames.has(item.forPuzzle))
+            fail(`clue item "${item.name}" references unknown puzzle "${item.forPuzzle}".`);
+    }
+    // The three structural faults real generations actually shipped -- an
+    // unplaced-or-double-placed puzzle, a puzzle with no clue item at all
+    // (unfixable by ANY items pass), and unreachable rooms -- must die HERE,
+    // before four detail passes build on bad bones.
+    for (const puzzle of skeleton.puzzles ?? []) {
+        if (puzzle.room && !roomNames.has(puzzle.room))
+            fail(`puzzle "${puzzle.name}" placed in unknown room "${puzzle.room}".`);
+        if (puzzle.rewardItem && !itemNames.has(puzzle.rewardItem))
+            fail(`puzzle "${puzzle.name}" rewards unknown item "${puzzle.rewardItem}".`);
+        const refs = doorRefs.get(puzzle.name) ?? 0;
+        if (puzzle.room && refs > 0)
+            fail(`puzzle "${puzzle.name}" is placed both in room "${puzzle.room}" AND on a door (exits[].puzzle) -- exactly one or the other.`);
+        if (!puzzle.room && refs === 0)
+            fail(`puzzle "${puzzle.name}" isn't placed anywhere -- set its "room", or reference it from one exits[].puzzle.`);
+        if (refs > 1)
+            fail(`puzzle "${puzzle.name}" is referenced by ${refs} doors -- a puzzle can only guard one.`);
+        const clue = skeleton.items.find(i => i.role === 'clue' && i.forPuzzle === puzzle.name);
+        if (!clue) {
+            // Loosened when the dossier says the runner can work this barrier
+            // unaided -- their bypass skill IS the way past (player note from a
+            // real failed generation: "it just needs a way past, and if the
+            // player has the means, it should be allowed").
+            if (!canBypassUnaided(player, puzzle.bypassType)) {
+                fail(`puzzle "${puzzle.name}" has no "clue"-role item with "forPuzzle": "${puzzle.name}" and its bypassType (${puzzle.bypassType ?? 'none'}) is not something this runner reliably handles -- add a "clue"-role Book item in a different room, or give the barrier a bypassType matching the runner's dossier strengths.`);
+            }
+        }
+        else {
+            if (!clue.room)
+                fail(`clue item "${clue.name}" needs a "room" (a different one than its puzzle's).`);
+            if (puzzle.room && clue.room === puzzle.room)
+                fail(`clue item "${clue.name}" sits in the SAME room as its puzzle "${puzzle.name}" -- place the clue in a different room.`);
+        }
+    }
+    if (!itemNames.has(skeleton.winCondition.item))
+        fail(`winCondition.item "${skeleton.winCondition.item}" is not in items.`);
+    if (!npcNames.has(skeleton.winCondition.toNpc))
+        fail(`winCondition.toNpc "${skeleton.winCondition.toNpc}" is not in npcs.`);
+    // Lock-and-key reachability. CRITICAL: edges are BIDIRECTIONAL -- the
+    // engine mirrors every declared exit into a shared two-way Door
+    // (room.addExit writes both sides), so a one-sided skeleton exit still
+    // connects both rooms in play. The first version of this walk was
+    // directed-only and falsely stranded rooms reachable via the mirrored
+    // direction, burning entire generations on a phantom fault.
+    const npcRoom = new Map(skeleton.npcs.map(n => [n.name, n.startLocation]));
+    const itemRoom = new Map();
+    for (const item of skeleton.items) {
+        if (item.room)
+            itemRoom.set(item.name, item.room);
+        else if (item.heldBy) {
+            const loc = npcRoom.get(item.heldBy);
+            if (loc)
+                itemRoom.set(item.name, loc);
+        }
+    }
+    const edges = [];
+    for (const room of skeleton.rooms) {
+        for (const exit of room.exits ?? []) {
+            edges.push({ a: room.name, b: exit.targetRoom, keyRequired: exit.keyRequired, puzzle: exit.puzzle });
+        }
+    }
+    const reachable = new Set([startRooms[0].name]);
+    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 keyLoc = edge.keyRequired ? itemRoom.get(edge.keyRequired) : undefined;
+            const passable = !!edge.puzzle || !edge.keyRequired || (keyLoc !== undefined && reachable.has(keyLoc));
+            if (passable) {
+                reachable.add(to);
+                grew = true;
+            }
+        }
+    }
+    const stranded = skeleton.rooms.filter(r => r.reachable !== false && !reachable.has(r.name));
+    if (stranded.length > 0) {
+        fail(`these rooms are unreachable from the start room given the locked doors and key placements: ${stranded.map(r => r.name).join(', ')}. Every key must be findable WITHOUT passing through the door it opens, and every normal room needs a route in (or mark it "reachable": false).`);
+    }
+}
+/**
+ * Auto-fixes skeleton faults that have exactly one sane resolution,
+ * instead of burning a whole retry on them. Today: a puzzle both placed
+ * in a room AND referenced by exactly one door keeps the DOOR placement
+ * (the model near-always meant "the door in that room" -- this exact
+ * fault killed two consecutive real generations). Returns notes for the
+ * log.
+ */
+export function normalizeSkeleton(skeleton) {
+    const notes = [];
+    const doorRefs = new Map();
+    for (const room of skeleton.rooms ?? []) {
+        for (const exit of room.exits ?? []) {
+            if (exit.puzzle)
+                doorRefs.set(exit.puzzle, (doorRefs.get(exit.puzzle) ?? 0) + 1);
+        }
+    }
+    for (const puzzle of skeleton.puzzles ?? []) {
+        if (puzzle.room && (doorRefs.get(puzzle.name) ?? 0) === 1) {
+            notes.push(`normalized: puzzle "${puzzle.name}" was double-placed (room + door); kept the door placement.`);
+            delete puzzle.room;
+        }
+    }
+    return notes;
+}
+/** Merges the skeleton's structure with the detail passes into a full seed. */
+export function assembleScene(skeleton, details, playerName) {
+    const roomDetail = new Map(details.rooms.map(r => [r.name, r]));
+    const npcDetail = new Map(details.npcs.map(n => [n.name, n]));
+    const puzzleDetail = new Map(details.puzzles.map(p => [p.name, p]));
+    const itemDetail = new Map(details.items.map(i => [i.name, i]));
+    const rooms = skeleton.rooms.map(room => ({
+        name: room.name,
+        description: roomDetail.get(room.name)?.description ?? room.concept,
+        roomType: roomDetail.get(room.name)?.roomType ?? room.roomType ?? 'Generic',
+        isStartRoom: room.isStartRoom,
+        reachable: room.reachable,
+        hasNode: room.hasNode,
+        nodeAccess: room.nodeAccess,
+        warded: room.warded,
+        owner: room.owner,
+        exits: (room.exits ?? []).map(e => ({
+            direction: e.direction,
+            targetRoom: e.targetRoom,
+            keyRequired: e.keyRequired,
+            puzzle: e.puzzle,
+        })),
+    }));
+    const npcs = skeleton.npcs.map(npc => {
+        const detail = npcDetail.get(npc.name);
+        return {
+            plane: npc.plane,
+            description: detail?.description ?? npc.concept,
+            dialogue: detail?.dialogue ?? [],
+            player: {
+                name: npc.name,
+                startLocation: npc.startLocation,
+                lifestyleChoices: [],
+                combat: detail?.combat,
+            },
+        };
+    });
+    const toItemJson = (skel, placed) => {
+        const detail = itemDetail.get(skel.name);
+        return {
+            name: skel.name,
+            description: detail?.description ?? skel.name,
+            size: detail?.size ?? 'Small',
+            category: skel.category,
+            shape: detail?.shape ?? 'Nondescript',
+            color: detail?.color ?? 'Gray',
+            texture: detail?.texture ?? 'Worn',
+            rating: detail?.rating ?? 'Common',
+            weight: typeof detail?.weight === 'number' ? detail.weight : 0.5,
+            currencyAmount: detail?.currencyAmount,
+            details: detail?.details,
+            transferable: detail?.transferable,
+            plane: skel.plane,
+            room: placed ? skel.room : undefined,
+            heldBy: placed ? skel.heldBy : undefined,
+        };
+    };
+    const startingSkels = skeleton.items.filter(i => i.role === 'starting');
+    const worldSkels = skeleton.items.filter(i => i.role !== 'starting');
+    const items = worldSkels.map(skel => toItemJson(skel, skel.role !== 'reward'));
+    const startingItems = startingSkels.map(skel => toItemJson(skel, false));
+    const puzzles = (skeleton.puzzles ?? []).map(puzzle => {
+        const detail = puzzleDetail.get(puzzle.name);
+        return {
+            name: puzzle.name,
+            room: puzzle.room,
+            riddle: detail?.riddle ?? puzzle.concept,
+            requiredPhrase: detail?.requiredPhrase ?? '',
+            successMessage: detail?.successMessage ?? 'It opens.',
+            failureMessage: detail?.failureMessage ?? 'Nothing happens.',
+            lockedMessage: detail?.lockedMessage,
+            requiresPuzzle: puzzle.requiresPuzzle,
+            rewardItem: puzzle.rewardItem,
+            bypassType: puzzle.bypassType,
+        };
+    });
+    const startRoom = skeleton.rooms.find(r => r.isStartRoom)?.name ?? skeleton.rooms[0]?.name ?? '';
+    return {
+        name: skeleton.name,
+        story: skeleton.story,
+        currency: { type: 'nuyen', authorityRoomTags: ['Bank'] },
+        residenceTiers: ['Street', 'Squatter', 'Low', 'Middle', 'High', 'Luxury'],
+        rooms,
+        npcs,
+        items,
+        puzzles,
+        player: {
+            name: playerName,
+            startLocation: startRoom,
+            lifestyleChoices: [{ type: 'residence', metadata: { tier: 'Street', location: startRoom } }],
+            startingItems,
+        },
+        winCondition: {
+            type: 'give',
+            item: skeleton.winCondition.item,
+            toNpc: skeleton.winCondition.toNpc,
+            rewardItem: skeleton.winCondition.rewardItem,
+            payout: skeleton.winCondition.payout,
+            completionMessage: skeleton.completionMessage,
+        },
+    };
+}
+/**
+ * Maps a validation failure to the chunk that owns the broken content, so
+ * a repair regenerates ONE pass instead of the whole scene. Anything
+ * structural (topology, placement, rosters) is skeleton-owned and restarts
+ * the pipeline with the error as feedback.
+ */
+export function classifyRepair(message) {
+    if (/no discoverable clue/i.test(message))
+        return 'items';
+    if (/startingItems|Win condition (item|rewardItem)|items\[/i.test(message))
+        return 'items';
+    if (/requiredPhrase|riddle|lockedMessage/i.test(message))
+        return 'puzzles';
+    if (/npcs\[|dialogue/i.test(message))
+        return 'npcs';
+    if (/rooms\[\d+\][^]*name/i.test(message))
+        return 'skeleton';
+    return 'skeleton';
+}
+//# sourceMappingURL=scene-chunks.js.map