@maka/maka-cli 5.3.16 → 5.4.0

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

@@ -0,0 +1,816 @@
+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';
+// The fixer's name is a fixed Shadowrun-lore convention (see the FIXER
+// CONVENTION comment in buildSchemaGuide below), not something generation
+// ever varies -- exported so callers that need to identify "the fixer"
+// specifically (as opposed to whoever a job's winCondition.toNpc happens to
+// be, which no longer has to be the same NPC) can check by name instead of
+// duplicating the literal string.
+export const FIXER_NAME = 'Mr. Johnson';
+function buildSchemaGuide(tier, previousFixerName) {
+    const scope = tier <= 1
+        ? '3 to 4 rooms, exactly 1 NPC, and exactly 1 puzzle'
+        : tier === 2
+            ? '4 to 5 rooms, 2 NPCs, and 1 to 2 puzzles'
+            : '5 to 6 rooms, 2 to 3 NPCs, and 2 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 the one lining up this one too. Reuse
+"${previousFixerName}" as this scene's fixer/job-giver (same name, same voice/personality),
+rather than inventing a new fixer character. Do not reintroduce them as a stranger; the
+runner already knows them.`
+        : '';
+    return `
+You are generating a small, self-contained Shadowrun-flavored text adventure "run" as JSON.
+This is job #${tier} in an ongoing campaign for the same runner -- make it noticeably more
+elaborate and higher-stakes than a first job would be, in proportion to how high the job
+number is.
+${continuity}
+
+Output ONLY raw JSON matching this exact shape -- no markdown fences, no commentary, no
+trailing text before or after the JSON object:
+
+{
+  "name": string,
+  "story": string, // 1-2 SHORT sentences, shown to the player before anything else
+                    // happens. This is a premise teaser, not a briefing -- name the
+                    // general shape of the trouble (a theft, a debt, a betrayal) and
+                    // nothing more. Never reveal the objective, a target's name or
+                    // location, a passphrase, a twist, or anything a player would need
+                    // to actually complete the run -- all of that belongs in the fixer's
+                    // "dialogue" instead, learned by "call"ing them once play begins (see
+                    // the fixer convention below). If this reads like a back-cover blurb
+                    // rather than a full plot summary, it's the right length.
+  "currency": { "type": "nuyen", "authorityRoomTags": ["Bank"] },
+  "residenceTiers": ["Street", "Squatter", "Low", "Middle", "High", "Luxury"],
+  "rooms": [
+    {
+      "name": string,
+      "description": string,
+      "roomType": string,
+      "isStartRoom"?: boolean, // set true on EXACTLY ONE room
+      "owner"?: string, // an NPC's name, if that NPC's room
+      "reachable"?: boolean, // defaults to true; set false ONLY for a fixer/employer's
+                              // remote hideout the player can never physically enter --
+                              // see the fixer convention below
+      "hasNode"?: boolean, // a live Matrix host in this room: a jacked-in player ("jack in")
+                            // can hack it from inside the Matrix to release the room's
+                            // locked doors FOR REAL. Mark 1-2 rooms in any corp/tech
+                            // location; leave street/wilderness rooms without. Ice NPCs
+                            // ("plane": "matrix") and paydata items ("plane": "matrix")
+                            // belong ONLY in hasNode rooms.
+      "warded"?: boolean, // an astral barrier: projecting mages ("project") cannot enter
+                           // this room astrally. Use on magically-secured rooms (a mage's
+                           // sanctum, a corp magical-security floor) -- it makes astral
+                           // scouting a puzzle, not a skeleton key. Use sparingly.
+      "exits": [
+        { "direction": "north"|"east"|"south"|"west"|"up"|"down", "targetRoom": string, "keyRequired"?: string,
+          "puzzle"?: string } // name of a "puzzles[]" entry that guards this door instead of (or as
+                              // well as) "keyRequired" -- see DOORS AS PUZZLES below
+      ]
+    }
+  ],
+  "npcs": [
+    {
+      "plane"?: "meat"|"matrix"|"astral", // default "meat". "matrix" = ICE: a security
+                            // program guarding a hasNode room -- only a jacked-in player
+                            // ever meets it (it fights with Logic-based pools; give it a
+                            // combat block with "logic" 4-7 and set its startLocation to
+                            // the hasNode room). "astral" = a SPIRIT: met only by
+                            // projecting mages -- give it "willpower"/"magic" 4-6 and
+                            // "intuition" 4+. Use at most one or two per scene, and only
+                            // where the location concept earns them.
+      "description": string, // private notes on personality/motives; never shown to the player directly
+      "dialogue": string[], // 2-4 short in-character lines. If this NPC is the fixer/job-giver,
+                             // THIS is where the actual briefing lives -- the objective, the
+                             // target, the stakes -- since "story" deliberately withholds it.
+      "player": { "name": string, "startLocation": string, "lifestyleChoices": [],
+        "combat"?: { "body": number, "agility": number, "reaction": number, "combatSkill": number,
+                     "magic"?: number, "strength"?: number, "willpower"?: number, "logic"?: number,
+                     "intuition"?: number, "charisma"?: number } }
+        // combat is OPTIONAL -- omit it for anyone who'd never be in a fight (a fixer, a
+        // bartender). When set, each attribute is 1-8: a soft civilian 1-2, a street-level
+        // runner 3-4 (the default when omitted), a hardened enforcer or bodyguard 5-6,
+        // elite corp security 7-8. Give a combat block (and an equipped-quality weapon/
+        // armor in "items" heldBy them) to any NPC the story expects might end up in a
+        // firefight -- combat is dice-pool based and gear quality feeds the dice.
+        // "magic" is innate arcane talent: omit (or 0) for the mundane majority. Set 3-6
+        // ONLY for a character whose concept is genuinely a mage/shaman/adept -- they'll
+        // know every spell (manabolt/heal/armor) innately with no gear needed, cast from
+        // raw talent, and should be described accordingly (their "description" should say
+        // they're Awakened). A Focus item still boosts them. Use sparingly: one Awakened
+        // NPC is a memorable threat, a scene full of them is noise.
+        // The optional extended attributes (all default ~3): "strength" (melee damage,
+        // carry), "willpower" (stun track, drain resist -- give mages 5+), "logic"
+        // (first aid, hacking -- a decker/street doc concept wants 5+), "intuition"
+        // (defense, perception), "charisma" (social presence). Set only the ones that
+        // define the character's concept; leave the rest to defaults.
+        // Rarer talents: "resonance" (technomancer -- rides the Matrix with no deck;
+        // use for a technomancer character concept only) and "adept": true (physical
+        // adept -- magic 4-6 channeled into meat combat, no spells, no projection).
+        // Never combine magic-casting, adept, and resonance on one character.
+        // A rival DECKER concept: "logic" 5-7 plus a Cyberdeck item heldBy them --
+        // their AI can then crack the player's PAN mid-fight ("hack <name>": jams
+        // the player's smartgun, cuts their AR). One per scene at most, and only
+        // where a decker belongs.
+    }
+  ],
+  "items": [
+    {
+      "name": string,
+      "description": string,
+      "size": "Tiny"|"Small"|"Medium"|"Large"|"VeryLarge",
+      "category": "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",
+      // "Cyberdeck" = the hardware REQUIRED to jack into the Matrix (a Commlink is
+      // calls/AR only). Its "rating" scales program damage, firewall, and its own
+      // damage track. Place one as loot/reward only when the story earns it -- a
+      // dead decker's kit, a smuggled prototype. If the scene has hasNode rooms
+      // with matrix-plane paydata, remember the player may need a deck to get it
+      // (deckers and technomancers bring their own way in).
+      // "Drone" = a launchable surveillance drone: the "drone" command sweeps all
+      // adjacent rooms for occupants/locks/nodes. Rigger flavor; rare loot.
+      // "Ammunition" = a spare clip/magazine: consumed by "reload" to refill a firearm
+      // (guns hold 10 rounds and every shot spends one). If a scene arms its NPCs or
+      // player with guns and expects a real firefight, place 1-2 Ammunition items
+      // somewhere findable.
+      // "Medical" = a single-use healing item (medkit, trauma kit): using it heals
+      // PHYSICAL combat damage, scaling with "rating", and consumes it. If this scene's
+      // story can plausibly end in a firefight (armed NPCs, a "will kill on sight"
+      // guard), place 1-2 Medical items somewhere findable -- a run with combat and no
+      // way to patch up is a meat grinder.
+      // "StimPatch" = a single-use combat drug: recovers STUN damage (spell drain,
+      // knockout track), scaling with "rating", but the crash costs 1 physical box.
+      // Worth placing one wherever magic gear appears, since casters accumulate stun.
+      //
+      // MAGIC GEAR (casting is gear-driven -- no innate mage stat):
+      //   - "SpellFormula": teaches ONE spell; its "name" MUST contain that spell's name.
+      //     The only spells that exist are "Manabolt", "Heal", and "Armor" -- e.g.
+      //     "Spell Formula: Manabolt", "Dog-Eared Heal Formula". Never invent other spells.
+      //   - "Grimoire": a spellbook -- teaches ALL three spells at once. Rarer find.
+      //   - "Focus": an amulet/wand/talisman that boosts casting power, scaling with
+      //     "rating" -- the magic equivalent of a better gun.
+      // Magic is optional flavor: most scenes need none. But if any puzzle here uses
+      // "bypassType": "spell", you MUST place at least one magic item (formula, grimoire,
+      // or focus) somewhere findable -- attempting to cast at a ward now requires magic
+      // gear, so a warded barrier with no magic gear in the scene has no bypass route.
+      // Anything wearable (a hoodie, gloves, a hat, boots...) MUST use one of
+      // the above wearable categories exactly -- never a generic catch-all
+      // like "Trinket" or "Document" for something meant to be worn.
+      "shape": string,
+      "color": string,
+      "texture": string,
+      "rating": "Common"|"Standard"|"Rare"|"Legendary"|"MilitaryGrade",
+      "weight": number, // kilograms, and it's REAL -- actors have a 50kg carry cap. Keep
+                         // items individually realistic (0.05 for a chip, ~1-2 for a pistol,
+                         // ~3-5 for armor); never give a carryable item a silly weight.
+      "currencyAmount"?: number, // only for Credstick/CurrencyContainer items
+      "room"?: string, // set this OR heldBy, never both, and never on a puzzle's reward item
+      "heldBy"?: string, // must be an NPC's name from "npcs", never the player
+      "owner"?: string,
+      "transferable"?: boolean,
+      "plane"?: "meat"|"matrix"|"astral", // default "meat". "matrix" = PAYDATA: a file that
+                          // exists only on the grid -- visible and takeable ONLY while the
+                          // player is jacked in ("jack in"). Place it in a "hasNode" room
+                          // (its "room"), category "Datachip" or "Document", weight 0. A
+                          // matrix-plane win-condition item makes the whole job a datarun:
+                          // the player MUST jack in, likely past ice, to finish. Use it
+                          // when the story is about stealing data, not things.
+      "details"?: string // deeper text shown only when the player closely examines or reads
+                          // this item (via "read", for a Book) -- NOT the same as "description",
+                          // which is always-visible flavor text shown just by looking at or
+                          // listing the item. A puzzle's clue text (see below) MUST go in
+                          // "details", never in "description" -- put it in "description" and the
+                          // player can never actually read it out.
+    }
+  ],
+  "puzzles": [
+    {
+      "name": string,
+      "room"?: string, // must match a room name -- OMIT this instead if "exits[].puzzle" (see DOORS
+                        // AS PUZZLES below) already places this puzzle on a door; a puzzle belongs
+                        // to exactly one of the two, never both and never neither.
+      "riddle": string, // What the player sees when they search this room (or approach this door),
+                         // shown verbatim -- NOT a cryptic riddle or poem to decode. Start with "You
+                         // see" (or "You find", "Set into the wall is", etc.) and name the barrier
+                         // plainly and concretely -- "You see a maglock safe.", "You see a biometric
+                         // scanner beside the door." -- then say what it demands (a code, a
+                         // fingerprint, a name spoken aloud, a passphrase), the way an NPC would
+                         // describe it, never as wordplay. See BYPASS TYPE below.
+      "requiredPhrase": string, // the exact code/passphrase/word that satisfies it -- ALL LOWERCASE, 2-5 plain words, no punctuation
+      "rewardItem"?: string, // must match an item name from "items" with no "room"/"heldBy" set. Required
+                              // for a "room"-anchored puzzle (this IS what solving it gets the player).
+                              // Omit for a door-anchored puzzle (exits[].puzzle) -- unlocking the door is
+                              // already the reward; only add one if there's a genuine bonus find too.
+      "successMessage": string,
+      "failureMessage": string,
+      "requiresPuzzle"?: string, // another puzzle's "name" that must be solved FIRST -- see below
+      "lockedMessage"?: string, // shown if the player tries to solve this before requiresPuzzle is met
+      "bypassType"?: "lockpick"|"hack"|"spell" // see BYPASS TYPE below -- omit if this barrier has no
+                                                // physical/technical/magical route past it
+    }
+  ],
+  // BYPASS TYPE: decide what a puzzle concretely IS before writing its "riddle" --
+  // a maglock, a keypad, a biometric scanner, a matrix node, a warded sigil, a
+  // guard who has to be talked past. That choice drives BOTH fields together:
+  // "riddle" describes THAT thing plainly (never as a cryptic riddle-poem), and
+  // "bypassType" names the matching physical/technical/magical route past it, if
+  // any: a literal lock, maglock, or keypad -> "lockpick", a terminal/console/
+  // matrix node or electronic scanner -> "hack", a ward or arcane sigil -> "spell".
+  // Leave "bypassType" unset only for a barrier with no such route (e.g. a purely
+  // social "convince the guard" puzzle) -- don't force one in just to use the
+  // mechanic, but don't invent a riddle-poem instead of a real barrier either.
+  //
+  // Either way, "requiredPhrase" is always a concrete, literal credential -- the
+  // code, the passphrase, the fingerprint owner's name, the words of the ward --
+  // never a wordplay answer to a puzzle. "riddle" states what the barrier wants
+  // without giving that credential away; the player finds it via a clue (below).
+  // When "bypassType" IS set, that same credential doubles as the safe route:
+  // "solve" with the right answer always works, while "pick"/"hack"/"cast" is
+  // the risky shortcut that skips finding it. That route is player-initiated
+  // and a genuine coin flip -- but failure is FATAL, ending the run outright
+  // (tripped alarm, security response, backlash -- whatever fits the barrier).
+  // Only give a puzzle "bypassType" when a real physical/technical/magical
+  // route past it makes sense; never attach it just to decorate a puzzle,
+  // since it's a real life-or-death choice the player is being offered.
+  //
+  // For EVERY puzzle above, the answer must be discoverable somewhere OTHER
+  // than the puzzle's own room (never the same room -- the player must go
+  // find it elsewhere). Either of these satisfies that, and the second is
+  // usually simpler to get exactly right:
+  //   (a) A companion clue item in "items": category "Book", "room" set to
+  //       a different room, whose "details" field directly states the
+  //       puzzle's exact "requiredPhrase" (a diary entry, scrawled note, or
+  //       manual that gives the answer away once someone reads it).
+  //   (b) The "requiredPhrase" IS a real item's exact "name" (any category),
+  //       placed with "room" set to a different room -- e.g. a riddle whose
+  //       answer is "obsidian keycard" and there's a real item literally
+  //       named "Obsidian Keycard" sitting elsewhere. Finding it and seeing
+  //       its name is the clue; no separate documentation needed.
+  //
+  // DOORS AS PUZZLES: a locked door can be secured by a real puzzle instead of
+  // (or as well as) a physical "keyRequired" item -- set "exits[].puzzle" to
+  // that puzzle's "name", and leave that puzzle's own "room" unset (it
+  // belongs to the door connecting two rooms, not either one). Everything
+  // above still applies exactly the same way -- it needs a "riddle"
+  // description, a discoverable clue elsewhere, and an optional matching
+  // "bypassType" -- the only difference is the payoff: solving or bypassing
+  // it unlocks the door rather than granting an item, so "rewardItem" should
+  // normally be omitted. Use this for a door that's more interesting than a
+  // "find the physical key" errand -- a keypad, a biometric scanner, a
+  // warded threshold -- and keep using plain "keyRequired" for a door that's
+  // just a mundane lock with a key sitting somewhere.
+  //
+  // FIXER CONVENTION: in Shadowrun, a fixer (whoever commissions a run) works
+  // over comms and essentially never meets a runner in person. If this scene's
+  // premise involves a job-giver/employer character (almost always true), name
+  // them EXACTLY "${FIXER_NAME}" -- in "npcs[].player.name", and in
+  // "winCondition.toNpc" too IF he's also the win condition's target (see
+  // BROKER, NOT ALWAYS THE DESTINATION below -- he often isn't). This is
+  // deliberate: in Shadowrun, "${FIXER_NAME}" is the in-universe slang for an
+  // anonymous corporate employer, not a real name -- every job's fixer goes by
+  // it regardless of who's actually behind the alias, and the runner never
+  // learns their real identity. Never invent a different name for this role.
+  // Give him his own room and mark that room "reachable": false -- an office,
+  // den, or safehouse the player will never set foot in. Give that room NO
+  // exits (or only exits to other "reachable": false rooms). "call" is the
+  // only way to reach him, and it requires a commlink on BOTH ends, equipped
+  // by the caller:
+  //   - Give the player a "Commlink"-category item in "startingItems" (or
+  //     placed somewhere findable in a reachable room).
+  //   - Give ${FIXER_NAME} his own "Commlink"-category item with "heldBy" set
+  //     to his name -- without one, he can never be reached at all.
+  //
+  // BROKER, NOT ALWAYS THE DESTINATION: ${FIXER_NAME}'s job is to commission
+  // the run and point the runner at what matters -- he does NOT have to be
+  // "winCondition.toNpc" himself. Often the more interesting choice is a
+  // DIFFERENT NPC entirely: someone ${FIXER_NAME} mentions in his own
+  // "dialogue" (a buyer, a target, a contact on the ground) who the runner
+  // then has to track down, meet, or call to actually finish the job. Both
+  // patterns are valid -- don't default to ${FIXER_NAME} as the
+  // winCondition.toNpc out of habit if the story is more interesting with
+  // someone else in that role. If you do introduce a separate contact this
+  // way, they need everything any other reachable NPC needs (a real
+  // startLocation; a commlink of their own if "call" is how the player is
+  // meant to reach them and their room is "reachable": false).
+  "player": {
+    "name": "Maka",
+    "startLocation": string, // must match the isStartRoom room's name
+    "lifestyleChoices": [{ "type": "residence", "metadata": { "tier": "Street", "location": string } }],
+    "startingItems": [ /* 3-5 items, same shape as above minus room/heldBy/owner */ ]
+  },
+  "winCondition": {
+    "type": "give",
+    "item": string, // must match an items[].name -- a MacGuffin the player must find and deliver
+    "toNpc": string, // must match an npcs[].player.name -- who wants it
+    "rewardItem"?: string, // optional bonus payoff item; must match an items[].name with no room/heldBy
+    "payout": number, // REQUIRED: the job's agreed pay in nuyen. The engine ACTUALLY transfers
+                       // this to the player on completion, and every NPC is told the exact
+                       // figure -- so this IS the number the fixer quotes. A round, streetwise
+                       // figure scaled to the job number: ~2000-6000 for job #1, roughly
+                       // half again more per job after that.
+    "completionMessage": string // shown to the player when they complete the job
+  }
+}
+
+Hard rules (a broken reference here will crash the game on load):
+- Every "exits[].targetRoom" MUST exactly match a "rooms[].name".
+- Every "npcs[].player.startLocation" MUST exactly match a "rooms[].name".
+- Every "items[].room" (if set) MUST exactly match a "rooms[].name".
+- Every "items[].heldBy" (if set) MUST exactly match an "npcs[].player.name".
+- Every puzzle in "puzzles[]" must be placed EXACTLY ONE way: either "puzzles[].room" matches a
+  "rooms[].name", OR exactly one "exits[].puzzle" matches its "name" (DOORS AS PUZZLES above) -- never
+  both, never neither.
+- Every "exits[].puzzle" (if set) MUST exactly match a "puzzles[].name".
+- "puzzles[].rewardItem" (if set) MUST exactly match an "items[].name", and that item must have neither "room" nor
+  "heldBy" set -- it doesn't exist anywhere in the world yet; solving the puzzle is what brings it into the
+  player's possession. If an NPC is guarding this reward, that's already implied by the puzzle needing to be
+  solved in their room -- do NOT ALSO make the reward item "heldBy" that NPC, which would mean two different,
+  disconnected copies of "the same" item end up existing (one granted by solving, one still sitting on the NPC).
+- "puzzles[].rewardItem" must NEVER be the same item as "winCondition.item" -- they need opposite placement
+  (one must have no room/heldBy, the other must have one), so no single item can satisfy both. If the story
+  wants the winCondition macguffin to feel puzzle-guarded, give the puzzle its OWN separate rewardItem instead
+  (a key, a note, access -- something that leads to the macguffin), and place "winCondition.item" itself
+  normally, with "room" or "heldBy" set.
+- Exactly one room must have "isStartRoom": true, and it must match "player.startLocation".
+- EVERY puzzle needs a discoverable clue in a room OTHER than that puzzle's "room" (for a
+  door-anchored puzzle, which has no "room" of its own, any room with the clue satisfies this) --
+  either pattern (a) or (b) above. A puzzle backed by neither, or a room-anchored one whose only
+  clue sits in its own room, is invalid -- the player must always have a discoverable way to find
+  the answer, and finding it must take some legwork.
+- "puzzles[].requiresPuzzle" (if set) MUST exactly match another "puzzles[].name" in this
+  same scene, must not reference itself, and chains must never cycle back on themselves
+  (A requires B requires A). A chain can be any length a puzzle count actually supports.
+- If a puzzle's riddle, clue, or the scene's "story" implies that doing something in one
+  place enables or unlocks something elsewhere (e.g. "cut the power to blind the cameras"),
+  that MUST be modeled as a real two-step (or longer) puzzle chain using "requiresPuzzle" --
+  never write a riddle or clue that implies a mechanic the JSON doesn't actually back up.
+  If there's only one puzzle in this scene, there's nothing to chain -- keep it self-
+  contained and don't reference another location or action that doesn't exist.
+- "winCondition.item" MUST exactly match an "items[].name", and that item MUST have either
+  "room" or "heldBy" set -- it needs a concrete, findable location in the world, exactly
+  like every other item. It must NOT be "heldBy" the "winCondition.toNpc" itself (the
+  player has to find it, not already have delivered it) -- place it in a room, or held by
+  a DIFFERENT NPC.
+- "winCondition.toNpc" MUST exactly match an "npcs[].player.name".
+- "winCondition.rewardItem" (if set) MUST exactly match an "items[].name" with neither
+  "room" nor "heldBy" set (same rule as a puzzle reward item).
+- This win-condition item is the CENTRAL plot object of the run's "story" -- something
+  stolen, owed, or lost that the winCondition.toNpc wants back or wants delivered.
+- "exits[].keyRequired" (if set) MUST exactly match an "items[].name", and that item MUST
+  have "room" or "heldBy" set to a concrete location -- never invent a key name that isn't
+  a real item. Never place that key's item in a room that is ONLY reachable by first going
+  through the very door it unlocks (that's an unsolvable soft-lock). The player must always
+  be able to reach the key through some path that doesn't require already being unlocked.
+- A room may be marked "reachable": false to represent somewhere the player can never
+  physically enter (a fixer's remote hideout, most commonly -- see the fixer convention
+  above). Such a room MUST have no exits, or exits ONLY to other "reachable": false rooms --
+  never an exit connecting it to a normally-reachable room, which would defeat the point.
+- Nothing the player must retrieve to finish the run -- a puzzle, a door's "keyRequired"
+  item, or the "winCondition.item" -- may be placed inside a "reachable": false room. The
+  player can never go get it.
+- If "winCondition.toNpc" is placed in a "reachable": false room, "call" (which requires a
+  commlink on both ends) is the only way to reach them, so BOTH of these must hold: the
+  player must have a way to get a "Commlink"-category item (in "startingItems", or findable
+  in a reachable room), AND "winCondition.toNpc" must itself hold a "Commlink"-category item
+  ("heldBy" set to their name) -- without one, they can never receive a call at all.
+
+Scope: ${scope}. Plus 4 to 6 general world items, one clue item per puzzle, the winCondition
+item and optional reward item, and the player's 3-5 starting items. Give it a gritty, noir
+Shadowrun tone: a fixer, a job, a locked door, a debt, a betrayal -- something in that vein.
+This is a fresh run, distinct from a generic "protect the lock" or "corp blackmail vault"
+premise.
+`.trim();
+}
+export class SceneSeedGenerator {
+    static maxAttempts = 3;
+    /**
+     * `tier` is 1 for a first job, 2+ for each successive "continue" --
+     * scales both the scope guidance in the prompt and, indirectly, the
+     * story's stakes. `previousFixerName`, when given, tells the model to
+     * keep using the same job-giver identity rather than inventing a new one
+     * every time "continue" is used.
+     */
+    static async generate(logFilePath, tier = 1, previousFixerName) {
+        if (!AI.isConfigured())
+            return null;
+        const logger = Logger.getInstance(logFilePath, { children: [], render: () => { } });
+        let lastError;
+        for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
+            try {
+                logger.write(`SceneSeedGenerator: tier ${tier} attempt ${attempt} of ${this.maxAttempts}`);
+                const candidate = await this.requestCandidate(tier, previousFixerName, lastError);
+                await this.dryRunValidate(candidate);
+                logger.write(`SceneSeedGenerator: generated a valid scene "${candidate.name}" on attempt ${attempt}`);
+                this.saveSeedToDisk(candidate, logFilePath, tier);
+                return candidate;
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err.message : String(err);
+                logger.write(`SceneSeedGenerator: attempt ${attempt} failed: ${lastError}`);
+            }
+        }
+        logger.write(`SceneSeedGenerator: giving up after ${this.maxAttempts} attempts, falling back to a static scene`);
+        return null;
+    }
+    /**
+     * 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) {
+        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));
+            logger.write(`SceneSeedGenerator: saved generated scene to ${seedPath}`);
+        }
+        catch (err) {
+            logger.error(`SceneSeedGenerator: failed to save generated scene to ${seedPath}: ${err}`);
+        }
+    }
+    static async requestCandidate(tier, previousFixerName, previousError) {
+        const schemaGuide = buildSchemaGuide(tier, previousFixerName);
+        const prompt = previousError
+            ? `${schemaGuide}\n\nYour previous attempt failed with this error -- fix it and try again: ${previousError}`
+            : schemaGuide;
+        let reply = await AI.ask(prompt);
+        // Models sometimes wrap their response in a markdown code fence despite instructions not to.
+        reply = reply.replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/i, '');
+        return JSON.parse(reply);
+    }
+    /**
+     * 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) {
+        // 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);
+        this.validateWinCondition(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;
+        reachable.add(startRoom);
+        let grew = true;
+        while (grew) {
+            grew = false;
+            for (const room of rooms) {
+                if (!reachable.has(room.name))
+                    continue;
+                for (const exit of room.exits ?? []) {
+                    if (reachable.has(exit.targetRoom))
+                        continue;
+                    const keyLocation = exit.keyRequired ? itemLocation.get(exit.keyRequired) : undefined;
+                    // A puzzle-guarded exit (see DOORS AS PUZZLES) is always treated
+                    // as eventually passable: validateClueItems already guarantees
+                    // every puzzle's answer is discoverable somewhere, and even
+                    // without it, pick/hack/cast is a real (if risky) route through.
+                    // Only a plain "keyRequired" door needs its key traced to a
+                    // reachable location first.
+                    const passable = !!exit.puzzle || !exit.keyRequired || (keyLocation !== undefined && reachable.has(keyLocation));
+                    if (passable) {
+                        reachable.add(exit.targetRoom);
+                        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) {
+        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);
+                const playerHasCommlink = (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}".`);
+                }
+            }
+        }
+    }
+    /**
+     * 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) {
+        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);
+            if (!hasBookClue && !hasNamedItemClue) {
+                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}", and no item elsewhere literally named "${puzzle.requiredPhrase}". Every puzzle needs one or the other.`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=scene-seed-generator.js.map