@maka/maka-cli 5.83.0 → 5.85.0

package/bundle/typescript/src/commands/game/sideQuest/utilities/ephemeral.js

@@ -0,0 +1,96 @@
+import { NPC } from '../models/npc.js';
+import { Logger } from './logger.js';
+import { CommandRegistry } from '../commands/command-registry.js';
+/**
+ * Bring one into the world. Returns the NPC, or null when the name is
+ * already taken -- the same refusal spawnCompanionShell makes, and for
+ * the same reason: two actors answering to one name is a bug nobody can
+ * see until a command picks the wrong one.
+ */
+export function spawnEphemeral(host, opts) {
+    if (host.scene.getActor(opts.name)) {
+        Logger.getInstance().write(`spawnEphemeral: name "${opts.name}" already in scene -- refusing.`);
+        return null;
+    }
+    const npc = new NPC({
+        dialog: [],
+        description: opts.description,
+        playerConstructorConfig: { playerName: opts.name, startLocation: opts.room, combat: opts.combat },
+    }, new CommandRegistry(host.scene));
+    npc.plane = 'meat';
+    // NOT allyOf, and NOT companionKind: an ephemeral belongs to nobody
+    // and is on no roster. Those two fields are what make a companion
+    // persist, follow, and take orders.
+    npc.ephemeral = { kind: opts.kind, until: opts.until, roomName: opts.room.name };
+    host.scene.addActor(npc);
+    host.scene.setCharacterLocation(npc, opts.room.name);
+    npc.scene = host.scene;
+    host.ephemerals.set(opts.name, npc.ephemeral);
+    Logger.getInstance().write(`Ephemeral spawned: ${opts.name} (${opts.kind}, until ${opts.until}) in ${opts.room.name}.`);
+    return npc;
+}
+/**
+ * Remove every ephemeral whose scope has ended.
+ *
+ * WHY NO SAVE HOOK IS NEEDED HERE, which is the ruling's reasoning and
+ * has to be true at exactly this line: ephemerals are never written to
+ * the save file, so there is nothing to reconcile on load. The obvious
+ * worry -- a save landing mid-fight, resurrecting a dead mob or erasing
+ * a live one -- is already answered upstream: requestSave's guards only
+ * write at safe beats and a fight is not one. So a load never sees a
+ * half-finished ephemeral, and this function is the only thing that
+ * ever ends one.
+ *
+ * Returns the names removed, so a caller can say so once.
+ */
+export function despawnEphemerals(host, opts) {
+    const removed = [];
+    for (const [name, mark] of [...host.ephemerals]) {
+        const ended = opts.all
+            ? true
+            : mark.until === 'fight'
+                ? opts.fightActive === false
+                // exchange- and room-scoped bodies both end when the player
+                // leaves: a walkout IS the end of the conversation.
+                : opts.playerRoomName !== undefined && opts.playerRoomName !== mark.roomName;
+        if (!ended)
+            continue;
+        if (host.scene.getActor(name) instanceof NPC)
+            host.scene.removeActor(name);
+        host.ephemerals.delete(name);
+        removed.push(name);
+    }
+    if (removed.length > 0) {
+        Logger.getInstance().write(`Ephemerals despawned: ${removed.join(', ')}.`);
+    }
+    return removed;
+}
+/**
+ * The two denials that make an ephemeral disposable, as prompt text.
+ *
+ * FULL LENGTH, DELIBERATELY. Everything else in an ephemeral's brief is
+ * trimmed hard -- no command help, no objective, no payout, no client,
+ * no wares, no history -- but the honesty pins are not where the budget
+ * gets saved. They are the majority of what remains precisely because
+ * the rest went, and trimming a denial is the exact economy that
+ * reintroduces the bug the denial exists to prevent. A shorter pin does
+ * not produce a shorter answer; it produces a confident wrong one.
+ */
+export function ephemeralDenials(role) {
+    return `
+YOU ARE A PASSING FACE, NOT A CHARACTER IN ANYONE'S STORY. You are ${role} -- here for
+this moment and no longer. You know nothing about any job, run, client, employer,
+objective, payout, or what these people are doing in this district beyond what is
+happening in front of you right now. You have no opinion about their business because you
+do not know they have any. If someone raises a job, a Johnson, a target, or a score, you
+have no idea what they are talking about and no curiosity about it -- that is somebody
+else's world and you are not in it.
+
+YOU CANNOT PROMISE, SELL, HIRE, OR HAND OVER ANYTHING. You quote no prices, offer no work,
+carry no goods to trade, and make no arrangements for later -- no favors owed, no "come
+find me", no meeting tomorrow. You will not be here tomorrow. Anything you agreed to would
+be an obligation nobody in the world can honor, and the person who trusted it would be
+worse off for having met you. If pressed for any of it, say plainly that it is not yours
+to give and point them at whoever actually handles such things.`;
+}
+//# sourceMappingURL=ephemeral.js.map

package/bundle/typescript/src/commands/game/sideQuest/utilities/ephemeral.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ephemeral.js","sourceRoot":"","sources":["../../../../../../../src/commands/game/sideQuest/utilities/ephemeral.ts"],"names":[],"mappings":"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"}

package/bundle/typescript/src/commands/game/sideQuest/utilities/first-aid.d.ts

@@ -0,0 +1,124 @@
+import type { Player } from '../models/player.js';
+import type { Item } from '../models/item.js';
+import { IDiceRoll } from './dice.js';
+/**
+ * FIRST AID (SR5 core p.205-206, with the gear rules at p.208/p.450).
+ *
+ * The engine already HAD a first-aid roll -- buried inside `use <medkit>`
+ * -- and it was wrong in a family rather than in one place, which is why
+ * this module exists at all. Every deviation below was measured against
+ * the book before it was touched:
+ *
+ *   canon                                  engine, before this module
+ *   -----------------------------------    ---------------------------------
+ *   threshold 2, NET hits heal a box       hits + 1 + quality: an all-miss
+ *                                          roll still closed a box
+ *   max healed = First Aid RATING          no cap at all -- kit quality was
+ *                                          the only thing that scaled
+ *   [Mental] limit (+ medkit rating)       no limit applied to the roll
+ *   once per set of wounds                 spammable
+ *   treats Stun OR Physical                physical only
+ *   critical glitch: +1D3 boxes            no glitch consequence
+ *   not after magical healing              no interaction with the spell
+ *
+ * The single most load-bearing consequence, and the reason this is worth
+ * doing: the RATING CAP inverts who is good at medicine. Before, an
+ * unskilled runner with an expensive kit out-healed a trained medic with
+ * a cheap one. Canon says the skill is the ceiling and the gear is the
+ * help -- medics matter.
+ *
+ * TWO ENGINE MAPPINGS, labelled as such (the ic.ts / astralMoveBudget
+ * house style: canon fixes the ratio, the unit is ours):
+ *
+ *  1. MEDKIT RATING. Canon rates medkits 1-6. This engine rates all gear
+ *     on one Common..MilitaryGrade tier (Item.qualityBonus, 0-4), because
+ *     gear tier is the whole progression system. So kit Rating is
+ *     `qualityBonus + 1`: a common kit is Rating 1, a milspec one Rating
+ *     5. The +1 is not decoration -- a Rating 0 kit would heal nothing in
+ *     an untrained hand, and canon has no Rating 0 medkit.
+ *
+ *  2. WIRELESS. p.208 gives a wireless kit a dice bonus; p.450 gives the
+ *     rating to the limit. This engine has no per-item wireless toggle,
+ *     and the Sixth World default is wireless-on, so kits are treated as
+ *     wireless and BOTH apply -- which is exactly what p.208's own worked
+ *     example does (Mental 6 + medkit 4 = limit 10).
+ *
+ * NOT MODELLED, deliberately, and each one is engine-lacks-the-noun
+ * rather than a rule we disagree with:
+ *
+ *   - "within 1 hour of the damage" (p.205). sideQuest has no elapsed
+ *     game clock -- see the same note in planes.ts -- so there is no
+ *     "when" to compare against. The once-per-set-of-wounds lock below
+ *     carries the anti-spam intent that the hour was there to serve.
+ *   - "Complex Action, one per Combat Turn per box" (p.206). The engine
+ *     has no action budget; combat is exchange-based and no verb spends
+ *     an action. Importing canon's PERMISSION to heal mid-fight without
+ *     its PRICE is a real gap, and it is called out in heal.ts.
+ */
+export declare const FIRST_AID_THRESHOLD = 2;
+export type WoundTrack = 'physical' | 'stun';
+export interface IFirstAidResult {
+    roll: IDiceRoll;
+    /** Boxes actually closed (0 on a failure or a critical glitch). */
+    healed: number;
+    /** Boxes ADDED by a critical glitch (p.206). */
+    worsened: number;
+    /** Hits over the threshold, before the cap and before armor. */
+    netHits: number;
+    /** The rating cap that applied -- skill, or kit rating if untrained. */
+    cap: number;
+    capBound: boolean;
+    halvedByArmor: boolean;
+    track: WoundTrack;
+}
+/**
+ * Canon rates medkits 1-6; this engine rates gear 0-4. See mapping 1 in
+ * the file header -- the +1 keeps a common kit useful in untrained hands.
+ */
+export declare function medkitRating(kit?: Item): number;
+/**
+ * The ceiling on boxes (p.205: "the maximum damage healable with the
+ * First Aid skill is equal to the skill's rating").
+ *
+ * Defaulting would make that ceiling ZERO -- the skill rating is 0, so a
+ * bare-handed amateur heals nothing however well they roll. p.208 is what
+ * rescues the untrained case: with a kit, "she can still make an
+ * untrained First Aid test using her Logic attribute minus 1 die and the
+ * device's rating IN PLACE OF her First Aid skill". The kit stands in for
+ * the skill, so it stands in as the cap too.
+ */
+export declare function firstAidCap(medic: Player, kit?: Item): number;
+/**
+ * First Aid + Logic (p.205), defaulting at Logic - 1 (p.130), plus the
+ * wireless kit's rating as dice (p.208) -- but only ONCE: when untrained
+ * the rating is already standing in for the skill, so adding the wireless
+ * bonus on top would pay the same kit twice.
+ *
+ * Quick Healer (p.77) and the medic's OWN wound modifiers (p.205 sends
+ * you to the Healing Modifiers table, and your own penalties travel with
+ * you) ride on top. Floored at 1: SR5 never rolls a zero pool.
+ */
+export declare function firstAidPool(medic: Player, kit?: Item): number;
+/** [Mental], plus the kit's rating (p.208's worked example: 6 + 4 = 10). */
+export declare function firstAidLimit(medic: Player, kit?: Item): number;
+/**
+ * "divide the net effect in half (rounded up) if the victim being treated
+ * is wearing any kind of full-body armor" (p.205-206).
+ *
+ * Read off the equipped slots by name, the same duck-typing the rest of
+ * the gear code uses (Item.isArmor, isFence) so generated kit works
+ * without a schema change.
+ */
+export declare function inFullBodyArmor(patient: Player): boolean;
+/**
+ * Why this treatment cannot happen, or undefined if it can. Ordered so
+ * the most informative refusal wins: a player who is out of options
+ * should be told the reason that is actually blocking them.
+ */
+export declare function firstAidRefusal(medic: Player, patient: Player, kit: Item | undefined, track: WoundTrack): string | undefined;
+/**
+ * Runs the test and applies the outcome. Callers MUST have cleared
+ * firstAidRefusal first -- this function assumes the treatment is legal
+ * and always consumes the once-per-wounds application.
+ */
+export declare function performFirstAid(medic: Player, patient: Player, kit: Item, track: WoundTrack): IFirstAidResult;

package/bundle/typescript/src/commands/game/sideQuest/utilities/first-aid.js

@@ -0,0 +1,209 @@
+import { rollPool } from './dice.js';
+import { mentalLimit } from './limits.js';
+/**
+ * FIRST AID (SR5 core p.205-206, with the gear rules at p.208/p.450).
+ *
+ * The engine already HAD a first-aid roll -- buried inside `use <medkit>`
+ * -- and it was wrong in a family rather than in one place, which is why
+ * this module exists at all. Every deviation below was measured against
+ * the book before it was touched:
+ *
+ *   canon                                  engine, before this module
+ *   -----------------------------------    ---------------------------------
+ *   threshold 2, NET hits heal a box       hits + 1 + quality: an all-miss
+ *                                          roll still closed a box
+ *   max healed = First Aid RATING          no cap at all -- kit quality was
+ *                                          the only thing that scaled
+ *   [Mental] limit (+ medkit rating)       no limit applied to the roll
+ *   once per set of wounds                 spammable
+ *   treats Stun OR Physical                physical only
+ *   critical glitch: +1D3 boxes            no glitch consequence
+ *   not after magical healing              no interaction with the spell
+ *
+ * The single most load-bearing consequence, and the reason this is worth
+ * doing: the RATING CAP inverts who is good at medicine. Before, an
+ * unskilled runner with an expensive kit out-healed a trained medic with
+ * a cheap one. Canon says the skill is the ceiling and the gear is the
+ * help -- medics matter.
+ *
+ * TWO ENGINE MAPPINGS, labelled as such (the ic.ts / astralMoveBudget
+ * house style: canon fixes the ratio, the unit is ours):
+ *
+ *  1. MEDKIT RATING. Canon rates medkits 1-6. This engine rates all gear
+ *     on one Common..MilitaryGrade tier (Item.qualityBonus, 0-4), because
+ *     gear tier is the whole progression system. So kit Rating is
+ *     `qualityBonus + 1`: a common kit is Rating 1, a milspec one Rating
+ *     5. The +1 is not decoration -- a Rating 0 kit would heal nothing in
+ *     an untrained hand, and canon has no Rating 0 medkit.
+ *
+ *  2. WIRELESS. p.208 gives a wireless kit a dice bonus; p.450 gives the
+ *     rating to the limit. This engine has no per-item wireless toggle,
+ *     and the Sixth World default is wireless-on, so kits are treated as
+ *     wireless and BOTH apply -- which is exactly what p.208's own worked
+ *     example does (Mental 6 + medkit 4 = limit 10).
+ *
+ * NOT MODELLED, deliberately, and each one is engine-lacks-the-noun
+ * rather than a rule we disagree with:
+ *
+ *   - "within 1 hour of the damage" (p.205). sideQuest has no elapsed
+ *     game clock -- see the same note in planes.ts -- so there is no
+ *     "when" to compare against. The once-per-set-of-wounds lock below
+ *     carries the anti-spam intent that the hour was there to serve.
+ *   - "Complex Action, one per Combat Turn per box" (p.206). The engine
+ *     has no action budget; combat is exchange-based and no verb spends
+ *     an action. Importing canon's PERMISSION to heal mid-fight without
+ *     its PRICE is a real gap, and it is called out in heal.ts.
+ */
+export const FIRST_AID_THRESHOLD = 2;
+/**
+ * Canon rates medkits 1-6; this engine rates gear 0-4. See mapping 1 in
+ * the file header -- the +1 keeps a common kit useful in untrained hands.
+ */
+export function medkitRating(kit) {
+    return kit ? kit.qualityBonus + 1 : 0;
+}
+/**
+ * The ceiling on boxes (p.205: "the maximum damage healable with the
+ * First Aid skill is equal to the skill's rating").
+ *
+ * Defaulting would make that ceiling ZERO -- the skill rating is 0, so a
+ * bare-handed amateur heals nothing however well they roll. p.208 is what
+ * rescues the untrained case: with a kit, "she can still make an
+ * untrained First Aid test using her Logic attribute minus 1 die and the
+ * device's rating IN PLACE OF her First Aid skill". The kit stands in for
+ * the skill, so it stands in as the cap too.
+ */
+export function firstAidCap(medic, kit) {
+    const trained = medic.skillRating('first-aid');
+    return trained > 0 ? trained : medkitRating(kit);
+}
+/**
+ * First Aid + Logic (p.205), defaulting at Logic - 1 (p.130), plus the
+ * wireless kit's rating as dice (p.208) -- but only ONCE: when untrained
+ * the rating is already standing in for the skill, so adding the wireless
+ * bonus on top would pay the same kit twice.
+ *
+ * Quick Healer (p.77) and the medic's OWN wound modifiers (p.205 sends
+ * you to the Healing Modifiers table, and your own penalties travel with
+ * you) ride on top. Floored at 1: SR5 never rolls a zero pool.
+ */
+export function firstAidPool(medic, kit) {
+    const trained = medic.skillRating('first-aid');
+    const rating = medkitRating(kit);
+    const base = trained > 0
+        ? medic.logic + trained + rating
+        : medic.logic - 1 + rating;
+    return Math.max(1, base
+        + medic.qualityBonus('healing')
+        + medic.augBonus('healing')
+        + medic.woundModifier);
+}
+/** [Mental], plus the kit's rating (p.208's worked example: 6 + 4 = 10). */
+export function firstAidLimit(medic, kit) {
+    return mentalLimit(medic) + medkitRating(kit);
+}
+/**
+ * "divide the net effect in half (rounded up) if the victim being treated
+ * is wearing any kind of full-body armor" (p.205-206).
+ *
+ * Read off the equipped slots by name, the same duck-typing the rest of
+ * the gear code uses (Item.isArmor, isFence) so generated kit works
+ * without a schema change.
+ */
+export function inFullBodyArmor(patient) {
+    const eq = patient.equipment;
+    for (const group of Object.values(eq)) {
+        if (!group)
+            continue;
+        for (const item of Object.values(group)) {
+            if (!item)
+                continue;
+            if (/full.?body|hardsuit|mil-?spec|full helmet/i.test(item.name))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Why this treatment cannot happen, or undefined if it can. Ordered so
+ * the most informative refusal wins: a player who is out of options
+ * should be told the reason that is actually blocking them.
+ */
+export function firstAidRefusal(medic, patient, kit, track) {
+    const self = medic === patient;
+    const who = self ? 'You' : patient.name;
+    const is = self ? 'are' : 'is';
+    // p.205: "First Aid can only be used if you have a medkit (even if you
+    // do not currently have supplies for it)."
+    if (!kit) {
+        return `First aid takes a medkit -- bare hands and good intentions don't close wounds. Buy one, or find a clinic ("treat").`;
+    }
+    if (patient.isDown()) {
+        // Canon has an answer for this (Stabilization, p.209, threshold 3),
+        // and this engine does not implement it. Saying so beats pretending.
+        return `${who} ${is} past first aid -- that's a stabilization job, and this street kit isn't it.`;
+    }
+    const hurt = track === 'physical' ? patient.damageTaken : patient.stunTaken;
+    if (hurt === 0) {
+        return track === 'physical'
+            ? `${who} ${is} not bleeding -- save the kit.`
+            : `${who} ${is} not winded -- save the kit.`;
+    }
+    // p.205: "First Aid may only be applied to a character once for that
+    // set of wounds." Note it is per CHARACTER, not per track -- so one
+    // application covers the patient, whichever track it treated. Canon is
+    // silent on split tracks, and this is the conservative reading.
+    if (patient.firstAidGiven) {
+        return `${who} ${is} already been worked on for these wounds -- there's nothing left first aid can do until ${self ? 'you take' : 'they take'} fresh damage. Rest, a clinic, or a heal spell from here.`;
+    }
+    // p.205: "First Aid may not be applied if the character has been
+    // magically healed."
+    if (patient.magicallyHealed) {
+        return `The mana already knit ${self ? 'your' : `${patient.name}'s`} wounds shut. First aid has nothing to add to a spell's work.`;
+    }
+    return undefined;
+}
+/**
+ * Runs the test and applies the outcome. Callers MUST have cleared
+ * firstAidRefusal first -- this function assumes the treatment is legal
+ * and always consumes the once-per-wounds application.
+ */
+export function performFirstAid(medic, patient, kit, track) {
+    const cap = firstAidCap(medic, kit);
+    const roll = rollPool(firstAidPool(medic, kit), firstAidLimit(medic, kit));
+    if (roll.criticalGlitch) {
+        // p.206: "A critical glitch on a First Aid Test increases the damage
+        // by 1D3 (1D6 / 2) boxes." 1D6/2 rounds up, giving 1-3.
+        const worsened = Math.ceil(rollPool(1).rolls[0] / 2);
+        if (track === 'physical')
+            patient.takeDamage(worsened);
+        else
+            patient.takeStun(worsened);
+        // AFTER the damage, never before: takeDamage clears firstAidGiven
+        // (fresh damage is a fresh set of wounds), and boxes opened by a
+        // botched treatment are part of the SAME set -- setting the flag
+        // first would let the fumbling medic immediately try again.
+        patient.firstAidGiven = true;
+        return {
+            roll, healed: 0, worsened, netHits: 0, cap,
+            capBound: false, halvedByArmor: false, track,
+        };
+    }
+    const netHits = Math.max(0, roll.hits - FIRST_AID_THRESHOLD);
+    let boxes = Math.min(netHits, cap);
+    const capBound = netHits > cap;
+    // Armor halves the EFFECT, applied after the cap so that treating
+    // through a hardsuit always bites. (The book says "net effect"; halving
+    // the net hits first would let a low cap absorb the penalty entirely,
+    // which reads against the rule's stated purpose -- "the difficulty of
+    // treating the patient through armor".)
+    const halvedByArmor = boxes > 0 && inFullBodyArmor(patient);
+    if (halvedByArmor)
+        boxes = Math.ceil(boxes / 2);
+    const healed = track === 'physical' ? patient.healDamage(boxes) : patient.healStun(boxes);
+    // The application is spent whether it went well or badly: canon says
+    // "may only be applied once", not "may only SUCCEED once".
+    patient.firstAidGiven = true;
+    return { roll, healed, worsened: 0, netHits, cap, capBound, halvedByArmor, track };
+}
+//# sourceMappingURL=first-aid.js.map

package/bundle/typescript/src/commands/game/sideQuest/utilities/first-aid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"first-aid.js","sourceRoot":"","sources":["../../../../../../../src/commands/game/sideQuest/utilities/first-aid.ts"],"names":[],"mappings":"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"}

package/bundle/typescript/src/commands/game/sideQuest/utilities/meet-location.d.ts

@@ -0,0 +1,37 @@
+import type { ISceneSeedJson } from '../types/seed/scene-seed.js';
+/**
+ * WHERE THE MEET ACTUALLY IS, read off the drafted seed.
+ *
+ * Item g5CgJgmw9ix6AcD78: "Krow said to meet at Mama Wu's, that
+ * shouldn't happen." There is no Mama Wu's. The fixer's pitch is
+ * AI-generated free text, and the brief told him the client "will hold
+ * the meet on-site" without telling him WHERE -- so a model writing a
+ * fixer's voice did the natural thing and invented a venue. The player
+ * then travelled to a scene that contains no such place.
+ *
+ * This is the codebase's signature defect: a NAME REFERRING TO NOTHING.
+ * The house cure is to resolve names against the real roster or room
+ * list and repair or reject, never to ship an unresolved one (see
+ * scene-chunks.ts resolveNamedRef). The same cure applies here, and it
+ * is better than a prohibition: the seed already KNOWS the answer, so
+ * the fixer can be told the truth rather than merely forbidden a lie.
+ * A brief that only says "don't invent one" leaves him with nothing to
+ * say and invites a vaguer dodge.
+ *
+ * THE MEET IS WHERE THE CLIENT STANDS, not the start room -- generation
+ * places the client "in a REACHABLE room that makes a characterful meet
+ * spot" (scene-chunks.ts), which is frequently not where the runner
+ * arrives. Falling back to the start room is still TRUE (it is where
+ * they land, and the client is always reachable from it), so the
+ * fallback degrades to vaguer rather than to wrong.
+ *
+ * IT LIVES HERE, not in call.ts, because ONE ANSWER IS THE WHOLE POINT.
+ * The reported bug is two sources disagreeing about where the meet is
+ * (the vetting on the item: "Krow directing the player to Mama Wu's,
+ * then a conflicting message from Mr. Vane at a different location"), so
+ * a resolver that only one of the speakers consults cannot fix it. Every
+ * surface that tells the player or an NPC where the meet is reads this
+ * function; if you are about to write the words "the meet" and a place
+ * name, call this instead.
+ */
+export declare function meetLocationFor(seed: ISceneSeedJson | undefined): string | undefined;

package/bundle/typescript/src/commands/game/sideQuest/utilities/meet-location.js

@@ -0,0 +1,51 @@
+/**
+ * WHERE THE MEET ACTUALLY IS, read off the drafted seed.
+ *
+ * Item g5CgJgmw9ix6AcD78: "Krow said to meet at Mama Wu's, that
+ * shouldn't happen." There is no Mama Wu's. The fixer's pitch is
+ * AI-generated free text, and the brief told him the client "will hold
+ * the meet on-site" without telling him WHERE -- so a model writing a
+ * fixer's voice did the natural thing and invented a venue. The player
+ * then travelled to a scene that contains no such place.
+ *
+ * This is the codebase's signature defect: a NAME REFERRING TO NOTHING.
+ * The house cure is to resolve names against the real roster or room
+ * list and repair or reject, never to ship an unresolved one (see
+ * scene-chunks.ts resolveNamedRef). The same cure applies here, and it
+ * is better than a prohibition: the seed already KNOWS the answer, so
+ * the fixer can be told the truth rather than merely forbidden a lie.
+ * A brief that only says "don't invent one" leaves him with nothing to
+ * say and invites a vaguer dodge.
+ *
+ * THE MEET IS WHERE THE CLIENT STANDS, not the start room -- generation
+ * places the client "in a REACHABLE room that makes a characterful meet
+ * spot" (scene-chunks.ts), which is frequently not where the runner
+ * arrives. Falling back to the start room is still TRUE (it is where
+ * they land, and the client is always reachable from it), so the
+ * fallback degrades to vaguer rather than to wrong.
+ *
+ * IT LIVES HERE, not in call.ts, because ONE ANSWER IS THE WHOLE POINT.
+ * The reported bug is two sources disagreeing about where the meet is
+ * (the vetting on the item: "Krow directing the player to Mama Wu's,
+ * then a conflicting message from Mr. Vane at a different location"), so
+ * a resolver that only one of the speakers consults cannot fix it. Every
+ * surface that tells the player or an NPC where the meet is reads this
+ * function; if you are about to write the words "the meet" and a place
+ * name, call this instead.
+ */
+export function meetLocationFor(seed) {
+    if (!seed)
+        return undefined;
+    const client = seed.client
+        ? seed.npcs?.find(n => n.player?.name === seed.client)
+        : undefined;
+    const clientRoom = client?.player?.startLocation;
+    // Only trust a room the scene really declares -- a startLocation that
+    // names no room is the same unresolved-name bug one level down, and
+    // repeating it into the fixer's mouth would be worse than silence.
+    const rooms = seed.rooms ?? [];
+    if (clientRoom && rooms.some(r => r.name === clientRoom))
+        return clientRoom;
+    return rooms.find(r => r.isStartRoom)?.name;
+}
+//# sourceMappingURL=meet-location.js.map

package/bundle/typescript/src/commands/game/sideQuest/utilities/meet-location.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meet-location.js","sourceRoot":"","sources":["../../../../../../../src/commands/game/sideQuest/utilities/meet-location.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,eAAe,CAAC,IAAgC;IAC9D,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM;QACxB,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,EAAE,IAAI,KAAK,IAAI,CAAC,MAAM,CAAC;QACtD,CAAC,CAAC,SAAS,CAAC;IACd,MAAM,UAAU,GAAG,MAAM,EAAE,MAAM,EAAE,aAAa,CAAC;IACjD,sEAAsE;IACtE,oEAAoE;IACpE,mEAAmE;IACnE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;IAC/B,IAAI,UAAU,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC;QAAE,OAAO,UAAU,CAAC;IAC5E,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,EAAE,IAAI,CAAC;AAC9C,CAAC"}

package/bundle/typescript/src/commands/game/sideQuest/utilities/perception.d.ts

@@ -0,0 +1,76 @@
+import type { Player } from '../models/player.js';
+/**
+ * THE PERCEPTION TEST (SR5 core p.135-136), shared by every verb that
+ * makes one.
+ *
+ * Item FNgptvRhbA5yMunbB, the player writing the spec in two sentences:
+ * '"look" should reveal items that are under a perception threshold.
+ * "search" is an active perception check'.
+ *
+ * The SPLIT they asked for already shipped (52ba4dda): `look` lists
+ * plain-sight goods with no test at all, which is p.135's own
+ * instruction -- characters "should always be able to observe what is
+ * immediately obvious without spending an action or making a test" --
+ * while `search` rolls. What had NOT shipped is the mechanical
+ * difference between the two rolls, and canon is specific about what it
+ * is:
+ *
+ *   "Perceiver is specifically looking/listening for it  +3"
+ *                              (p.135-136, Perception Test Modifiers)
+ *
+ * That +3 IS the active/passive distinction. Without it, `search` was an
+ * active perception check in name while rolling the same pool as the
+ * passive glance -- the player's second sentence unimplemented, one
+ * layer below the one that was fixed.
+ *
+ * AND THE BRACKET IS A LIMIT. `Perception + Intuition [Mental]`: neither
+ * verb applied one, so a huge pool could count unlimited hits. Limits
+ * cap HITS, never dice (utilities/dice.ts, and the house rule at the top
+ * of CLAUDE.md).
+ *
+ * ONE FUNCTION, BOTH CALLERS, deliberately. look.ts and search.ts each
+ * built this pool inline and had already drifted apart; that is the same
+ * one-caller drift that let the meet address disagree with itself
+ * (g5CgJgmw9ix6AcD78) and the same duplicated-mechanic shape that let
+ * `use <medkit>` diverge from `heal`. If you are about to roll
+ * Perception, roll it here.
+ */
+/** p.135-136: the modifier for deliberately looking, which is what makes
+ *  an active search mechanically different from a passive glance. */
+export declare const ACTIVELY_LOOKING = 3;
+export interface IPerceptionTest {
+    pool: number;
+    /** The bracket. Undefined only when the actor has no limit to apply --
+     *  see the Matrix note below; rollPool refuses a zero limit loudly. */
+    limit: number | undefined;
+}
+export interface IPerceptionOpts {
+    /** True for a deliberate hunt (`search`), false for a glance (`look`). */
+    active?: boolean;
+    /** Matrix Search only: a loaded Browse program is purpose-built for it. */
+    browse?: number;
+}
+/**
+ * ON THE GRID IT IS A DIFFERENT TEST WITH A DIFFERENT BRACKET. Matrix
+ * Search is Computer + Logic [Data Processing], so the Mental limit does
+ * NOT apply out there -- capping a decker's sweep by their Willpower
+ * would be a fresh deviation dressed as a fix. The engine takes the
+ * best of Perception and Computer so pre-Computer deckers lose nothing
+ * (a standing allowance, older than this function).
+ *
+ * Data Processing reads 0 for an actor with no deck at all; that is a
+ * caller's missing gate rather than a real limit, so it degrades to
+ * unlimited here instead of handing rollPool a zero it would reject.
+ */
+export declare function perceptionTest(actor: Player, opts?: IPerceptionOpts): IPerceptionTest;
+/**
+ * PERCEPTION THRESHOLDS (p.136). Named because the numbers appear in
+ * player-facing text and in cover reads, and a bare 2 or 4 in three
+ * files is how they drift.
+ */
+export declare const PERCEPTION_THRESHOLD: {
+    /** Street sign, pedestrian, conversation, silenced gunfire. */
+    readonly normal: 2;
+    /** Secret door, needle in a haystack, subvocal speech. */
+    readonly hidden: 4;
+};