@maka/maka-cli 5.201.0 → 5.203.0

package/bundle/typescript/src/commands/game/sideQuest/models/scene.js

@@ -628,7 +628,23 @@ export class Scene extends AbstractScene {
         this.logger.write(`Actor with name ${actor.name} has been added to the scene.`);
         this.actors.set(actor.name, actor);
     }
-    removeActor(name) {
+    /**
+     * Take an actor out of the world.
+     *
+     * `spill` (default true) is whether what they carried lands on the
+     * floor. TRUE IS A BODY: a kill has already been stripped by
+     * Room.layOutBody, and anything left is the leftover a corpse drops.
+     * FALSE IS A DEPARTURE (utilities/ephemeral.ts despawnEphemerals): a
+     * ganger who walks off their corner, an officer whose sweep moved on,
+     * takes their gun with them. Before kits (catalog v21) ephemerals
+     * carried nothing so the distinction cost nothing; the day they got
+     * a Browning and an armor vest, walking away from a street corner
+     * rained both onto the pavement, per ganger, per block -- and the
+     * governor's founding denial is that an ephemeral cannot create
+     * obligations. A gun the world has to keep track of after the body
+     * is gone is exactly that.
+     */
+    removeActor(name, opts = {}) {
         const actor = this.actors.get(name);
         // Removal is cleanup, not an assertion: a concurrent kill resolution
         // (or any double-remove) finding the actor already gone is a no-op,
@@ -639,6 +655,10 @@ export class Scene extends AbstractScene {
             return;
         }
         const room = actor.currentLocation;
+        const spill = opts.spill !== false;
+        if (!spill && room) {
+            this.logger.write(`removeActor: ${actor.name} leaves ${room.name} with everything they carried.`);
+        }
         // One consolidated observer line for the whole spill, not one stilted
         // "on death drops" line per item -- and everything that falls is IN
         // PLAIN SIGHT (see Room.plainSightItems): the player just watched it
@@ -649,7 +669,7 @@ export class Scene extends AbstractScene {
         // "counter" that didn't exist in the room (the note had ridden a
         // crew member's pack from a different scene entirely).
         const fallSpot = actor.atSpot;
-        if (room && actor.inventory) {
+        if (spill && room && actor.inventory) {
             const items = actor.inventory.getAllItems();
             for (const item of items) {
                 const didDrop = actor.inventory.transferItemTo(item.name, room.inventory);
@@ -666,7 +686,7 @@ export class Scene extends AbstractScene {
         // holstered pistol are exactly the loot a runner expects to strip.
         // Without this, everything an NPC had equipped would silently vanish
         // from the world on death.
-        if (room && actor.equipment) {
+        if (spill && room && actor.equipment) {
             for (const group of Object.values(actor.equipment)) {
                 if (!group)
                     continue;

package/bundle/typescript/src/commands/game/sideQuest/npc-kits.js

@@ -0,0 +1,295 @@
+import { augFor, itemFromCatalog, npcKitFor } from './utilities/catalog.js';
+import { Category } from './types/shared/item-enum.js';
+import { Logger } from './utilities/logger.js';
+// ============================================================================
+// Tiers
+// ============================================================================
+/**
+ * WHICH KIT A SITE'S SECURITY TIER FIELDS. The slugs match the shipped
+ * rows (maka-cli.com full-catalog.json v21); a row that is missing
+ * resolves to no kit, per the file comment.
+ */
+export const KIT_FOR_TIER = {
+    0: 'thugs',
+    1: 'gangers',
+    2: 'corp-security',
+    3: 'police-patrol',
+    4: 'organized-crime',
+    5: 'elite-corp-security',
+    6: 'elite-special-forces',
+};
+export function kitSlugForTier(tier) {
+    return KIT_FOR_TIER[tier];
+}
+/**
+ * THE MOST A JOB OF THIS SIZE PLAUSIBLY FIELDS. `campaignTier` is the
+ * job number (buildSkeletonPrompt's `tier`), NOT the security tier --
+ * the two words collide and this is the one place they meet. Job #1 is
+ * a warehouse, not an arcology: elite corporate security (PR 5) is a
+ * tier-3+ problem, and PR 6 special forces never come from a generated
+ * draft at all -- a hand-authored seed may declare them.
+ */
+export function maxSecurityTierFor(campaignTier) {
+    if (campaignTier <= 1)
+        return 2;
+    if (campaignTier === 2)
+        return 3;
+    return 5;
+}
+/** What a draft that declared nothing gets: a gang block for job #1, a
+ *  corporate office for #2, a patrolled site after that. */
+export function defaultSecurityTierFor(campaignTier) {
+    if (campaignTier <= 1)
+        return 1;
+    if (campaignTier === 2)
+        return 2;
+    return 3;
+}
+/**
+ * CLAMP, NEVER REJECT. A model that wrote "securityTier": 9, or "high",
+ * or nothing, has still written a usable scene; failing the skeleton
+ * over it would spend a real generation retry on a number the engine
+ * can repair in one line. Same policy as the keyed-door and keyItem
+ * repairs in scene-factory.ts.
+ */
+export function clampSecurityTier(raw, campaignTier) {
+    const n = typeof raw === 'number' ? raw : Number(raw);
+    const base = Number.isFinite(n) ? Math.round(n) : defaultSecurityTierFor(campaignTier);
+    return Math.max(0, Math.min(maxSecurityTierFor(campaignTier), base));
+}
+/**
+ * ROUGHLY WHAT A RANK-AND-FILE GRUNT OF THIS TIER ROLLS, attack pool
+ * plus defense pool, read off the p.381-384 statblocks (Agility +
+ * weapon skill + smartlink/toner; Reaction + Intuition/2 + wired
+ * reflexes). The party's own figure (scene-chunks.ts partyStrength) is
+ * on the same scale, and a party that clears this by a margin draws
+ * the tier's lieutenant.
+ */
+export function expectedStrengthFor(securityTier) {
+    const table = { 0: 11, 1: 12, 2: 13, 3: 12, 4: 16, 5: 25, 6: 29 };
+    return table[Math.max(0, Math.min(6, securityTier))] ?? 12;
+}
+/** The margin past expectedStrengthFor at which a site posts its lieutenant. */
+export const LIEUTENANT_MARGIN = 3;
+export function partyDrawsLieutenant(partyStrength, securityTier) {
+    return partyStrength > expectedStrengthFor(securityTier) + LIEUTENANT_MARGIN;
+}
+// ============================================================================
+// Group Edge and morale (p.379-380)
+// ============================================================================
+/** p.380: "a team of grunts has a Group Edge equal to its Professional Rating." */
+export function groupEdgeFor(professionalRating) {
+    return Math.max(0, Math.min(6, Math.round(professionalRating)));
+}
+/**
+ * p.379-380, verbatim in spirit: PR 0 "will flee if somebody in their
+ * group goes down"; PR 1-2 "retreat if more than a quarter of their
+ * team is taken out"; PR 3-4 "withdraw after casualties exceed half";
+ * PR 5-6 "will not break -- they fight to the last man".
+ */
+export function moraleBandFor(professionalRating) {
+    if (professionalRating <= 0)
+        return 'one-drops';
+    if (professionalRating <= 2)
+        return 'quarter';
+    if (professionalRating <= 4)
+        return 'half';
+    return 'never';
+}
+/** Does a team of `total` that has lost `casualties` break at this PR? */
+export function moraleBreaks(professionalRating, casualties, total) {
+    if (total <= 0 || casualties <= 0)
+        return false;
+    switch (moraleBandFor(professionalRating)) {
+        case 'one-drops': return casualties >= 1;
+        case 'quarter': return casualties > total / 4;
+        case 'half': return casualties > total / 2;
+        case 'never': return false;
+    }
+}
+/** The line the room hears when a team breaks, by how trained it was. */
+export function moraleBreakLine(name, band) {
+    switch (band) {
+        case 'one-drops': return `${name} sees the body drop and wants no part of this -- hands up, backing off.`;
+        case 'quarter': return `${name} has seen enough of their own go down -- weapon lowered, backing out of it.`;
+        default: return `${name} calls it: too many down. Weapon down, hands where you can see them.`;
+    }
+}
+// ============================================================================
+// Outfitting
+// ============================================================================
+/**
+ * WHAT AN NPC WEARS OR HOLDS, out of what a kit puts in its pack. The
+ * one list, shared by scene-factory's equip step and the ephemeral
+ * governor, so a guard built by a seed and a ganger spawned on a corner
+ * dress the same way. Weapons and armor only: a commlink stays in the
+ * pocket, and plot items (keys, chips) stay in inventory where "give"
+ * and the loot lane expect them.
+ */
+export const NPC_EQUIP_CATEGORIES = new Set([
+    Category.Weapon, Category.MeleeWeapon, Category.RangedWeapon,
+    Category.Armor, Category.BodyArmor, Category.ArmorClothing, Category.Shield,
+    Category.Helmet, Category.ArmArmor, Category.LegArmor, Category.Boots, Category.Gloves,
+]);
+const WEAPON_CATEGORIES = new Set([
+    Category.Weapon, Category.MeleeWeapon, Category.RangedWeapon,
+]);
+/**
+ * Slots every weapon and armor piece in the pack into the actor's
+ * equipment, FIRST WEAPON WINS. `equip` swaps, so an unguarded loop
+ * over a pack holding a pistol and a knife ends with the knife in hand
+ * and the pistol holstered -- the exact bug archetypes.ts:outfitArchetype
+ * documents for runners, reproduced here for everyone else. Armor
+ * layers (a helmet over a jacket), so only weapons are guarded.
+ */
+export function equipKitIntoHands(actor) {
+    for (const item of [...actor.inventory.getAllItems()]) {
+        if (!NPC_EQUIP_CATEGORIES.has(item.category))
+            continue;
+        if (WEAPON_CATEGORIES.has(item.category) && actor.getCarriedWeapon())
+            continue;
+        try {
+            actor.equip(item);
+        }
+        catch { /* nothing to slot it into -- stays holstered */ }
+    }
+}
+/**
+ * STAMP A KIT ONTO AN NPC. The NPC analogue of archetypes.ts
+ * outfitArchetype, minus the chargen ledger and the credstick.
+ *
+ * INTO THE PACK, NOT INTO THE HANDS. This adds gear to inventory and
+ * stops; equipping is the caller's step (scene-factory's Step 4.05 for
+ * a seeded NPC, equipKitIntoHands for an ephemeral), because the seeded
+ * path has an author to defer to: an item the seed put in this NPC's
+ * hands with `heldBy` is the author speaking, and the kit skips its
+ * own weapon rather than argue -- `respectCarried` below. Armor still
+ * layers.
+ *
+ * Idempotent on augs and qualities (hasAug / the Set), so a kit applied
+ * twice does not double-install wired reflexes.
+ */
+export function outfitNpcKit(npc, kit, opts = {}) {
+    const logger = Logger.getInstance();
+    const lt = opts.lieutenant ? kit.lieutenant : undefined;
+    const attrs = { ...kit.attributes, ...(lt?.attributes ?? {}) };
+    const skills = { ...kit.skills, ...(lt?.skills ?? {}) };
+    const gear = lt?.gear ?? kit.gear;
+    const ammo = lt?.ammo ?? kit.ammo;
+    const augs = [...kit.augs, ...(lt?.augs ?? [])];
+    const qualities = [...kit.qualities, ...(lt?.qualities ?? [])];
+    const spells = [...kit.spells, ...(lt?.spells ?? [])];
+    const adeptPowers = { ...(kit.adeptPowers ?? {}), ...(lt?.adeptPowers ?? {}) };
+    npc.kit = kit.key;
+    npc.professionalRating = kit.professionalRating;
+    if (opts.lieutenant)
+        npc.lieutenant = true;
+    // The faction feature (factions.ts) ships rows and rules and no seed
+    // wiring; a kit row knows who fields it, so the gap closes here. An
+    // author's explicit faction still wins.
+    if (kit.faction && !npc.faction)
+        npc.faction = kit.faction;
+    npc.body = attrs.body;
+    npc.agility = attrs.agility;
+    npc.reaction = attrs.reaction;
+    npc.strength = attrs.strength;
+    npc.willpower = attrs.willpower;
+    npc.logic = attrs.logic;
+    npc.intuition = attrs.intuition;
+    npc.charisma = attrs.charisma;
+    if (attrs.magic !== undefined)
+        npc.magic = attrs.magic;
+    if (attrs.resonance !== undefined)
+        npc.resonance = attrs.resonance;
+    if (attrs.adept !== undefined)
+        npc.adept = attrs.adept;
+    // Grunts have no Edge POOL of their own (p.380): the team shares one
+    // equal to its PR, held on the CombatEncounter. The RATING stays on
+    // the actor because Player.consumeEdgeBoost adds `this.edge` dice
+    // when a boost lands -- p.56's "add Edge to the dice pool" -- and a
+    // grunt's Edge for that purpose is the group's. edgeRemaining is 0
+    // so nothing reads a per-actor pool.
+    npc.edge = groupEdgeFor(kit.professionalRating + (opts.lieutenant ? 1 : 0));
+    npc.edgeRemaining = 0;
+    // THE KIT IS THE STATLINE: replace, never merge. A `combat.skills`
+    // block a model wrote for a guard is superseded by the book's, and a
+    // merge would keep a dead key like `firearms` alive beside the live ones.
+    npc.skills = { ...skills };
+    const top = Object.entries(skills).sort((a, b) => b[1] - a[1])[0];
+    if (top)
+        npc.combatSkill = top[1];
+    for (const key of qualities) {
+        if (!npc.qualities.has(key))
+            npc.addQuality(key);
+    }
+    for (const key of augs) {
+        const aug = augFor(key);
+        if (aug && !npc.hasAug(key))
+            npc.installAug(aug);
+        else if (!aug)
+            logger.write(`npc-kit ${kit.key}: augmentation "${key}" has no row -- skipped.`);
+    }
+    if (spells.length > 0)
+        npc.knownSpells = [...new Set([...(npc.knownSpells ?? []), ...spells])];
+    if (Object.keys(adeptPowers).length > 0) {
+        npc.adept = true;
+        npc.adeptPowers = { ...(npc.adeptPowers ?? {}), ...adeptPowers };
+    }
+    const carriesWeapon = opts.respectCarried
+        && npc.inventory.getAllItems().some(i => WEAPON_CATEGORIES.has(i.category));
+    let firstGun;
+    for (const slug of gear) {
+        let item;
+        try {
+            item = itemFromCatalog(slug);
+        }
+        catch (err) {
+            // A missing gear row is a catalog problem, logged and survived:
+            // the guard is a little lighter, not absent. The kit suite walks
+            // every slug so this never reaches a player from a shipped row.
+            logger.write(`npc-kit ${kit.key}: ${err instanceof Error ? err.message : String(err)} -- skipped.`);
+            continue;
+        }
+        if (carriesWeapon && WEAPON_CATEGORIES.has(item.category))
+            continue;
+        try {
+            npc.addInventory(item);
+        }
+        catch (err) {
+            logger.write(`npc-kit ${kit.key}: could not give ${npc.name} ${item.name} (${err instanceof Error ? err.message : 'carry cap?'}).`);
+            continue;
+        }
+        item.owner = npc.name;
+        if (!firstGun && item.isFirearm())
+            firstGun = item;
+    }
+    // p.433-434: what is loaded shifts the gun's line -- this is how the
+    // PR 6 HK 227 gets its APDS AP -4 without the row lying about the gun.
+    if (ammo && firstGun) {
+        const round = itemFromCatalogQuiet(ammo);
+        if (round)
+            firstGun.loadedAmmo = round.name;
+    }
+    logger.write(`npc-kit: ${npc.name} outfitted as ${kit.key}${opts.lieutenant ? ' (lieutenant)' : ''} -- PR ${kit.professionalRating}, ${gear.length} piece(s).`);
+}
+function itemFromCatalogQuiet(slug) {
+    try {
+        return itemFromCatalog(slug);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Resolve-and-outfit in one call; a slug with no row is a no-op. Returns whether a kit landed. */
+export function outfitNpcBySlug(npc, slug, opts = {}) {
+    if (!slug)
+        return false;
+    const kit = npcKitFor(slug);
+    if (!kit) {
+        Logger.getInstance().write(`npc-kit: no row for "${slug}" -- ${npc.name} keeps their attribute block.`);
+        return false;
+    }
+    outfitNpcKit(npc, kit, opts);
+    return true;
+}
+//# sourceMappingURL=npc-kits.js.map

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

@@ -952,6 +952,40 @@ export function factionFor(key) {
 export function catalogFactions() {
     return listOfKind('faction', factionFor);
 }
+/**
+ * AN NPC KIT ROW, rebuilt as the engine reads it (catalog v21, "everyone
+ * is basically naked"). Same contract as factionFor: the rows live on
+ * maka-cli.com, an unknown slug answers undefined, and npc-kits.ts
+ * treats that as "no kit" -- a cached catalog from before v21 builds
+ * NPCs exactly as the engine always did.
+ */
+export function npcKitFor(key) {
+    return kindIndex('npc-kit', row => {
+        const k = row.npcKit;
+        return {
+            key: row.slug,
+            name: row.name,
+            description: row.description,
+            professionalRating: k.professionalRating,
+            ...(k.faction !== undefined ? { faction: k.faction } : {}),
+            sort: k.sort,
+            attributes: { ...k.attributes },
+            skills: { ...k.skills },
+            gear: [...k.gear],
+            ...(k.ammo !== undefined ? { ammo: k.ammo } : {}),
+            augs: [...(k.augs ?? [])],
+            qualities: [...(k.qualities ?? [])],
+            spells: [...(k.spells ?? [])],
+            ...(k.adeptPowers !== undefined ? { adeptPowers: { ...k.adeptPowers } } : {}),
+            ...(k.lieutenant !== undefined ? { lieutenant: { ...k.lieutenant } } : {}),
+            page: row.page ?? '',
+        };
+    }).get(key);
+}
+/** Every NPC kit the resolved catalog knows. */
+export function catalogNpcKits() {
+    return listOfKind('npc-kit', npcKitFor);
+}
 /** Every metamagic and echo the resolved catalog knows. */
 export function catalogMetamagics() {
     return listOfKind('metamagic', metamagicFor);

package/bundle/typescript/src/commands/game/sideQuest/utilities/combat-turn.js

@@ -1,6 +1,7 @@
 import { rollInitiativeScore, formatInitiative, INITIATIVE_PASS_DROP, rollPool, formatRoll } from './dice.js';
 import { ActionBudget } from './action-budget.js';
 import { runNpcActionPhase } from './npc-combat-brain.js';
+import { groupEdgeFor } from '../npc-kits.js';
 export function arenaKey(a) {
     return a.kind === 'room' ? `room:${a.room.name}` : a.kind === 'host' ? `host:${a.host.name}` : 'grid:open';
 }
@@ -114,6 +115,20 @@ export class CombatEncounter {
     pairs = new Map();
     surrenderSeenAt = new Map();
     running = false;
+    /**
+     * GRUNT TEAMS BY KIT (p.379-380, npc-kits.ts). Every kitted NPC who
+     * enters the fight is rostered under its kit slug, and the roster is
+     * the denominator morale reads -- a team that started four and lost
+     * two has lost half, whether or not the dead are still actors. Group
+     * Edge is a pool per kit, seeded to the PR on first sight (+1 with a
+     * lieutenant, p.380-381) and spent by the brain one point per grunt
+     * per fight. Keyed by KIT rather than by side because one scene can
+     * field a PR 1 gang and a PR 3 patrol, and the book prices them
+     * separately.
+     */
+    kitRoster = new Map();
+    groupEdge = new Map();
+    edgeSpentBy = new Set();
     /** Every human phase that began -- a seam for tests and for any future
      *  phase clock; nothing plays the phase for a human (the fight
      *  autopilot was retired 2026-09-07: a phase you commit with "end
@@ -213,8 +228,80 @@ export class CombatEncounter {
             acted: false, delayed: false, surprised: false,
         };
         this.participants.push(p);
+        this.rosterGrunt(actor);
         return p;
     }
+    /** Put a kitted NPC on its team's roster; seed the team's Group Edge on first sight. */
+    rosterGrunt(actor) {
+        const npc = actor;
+        if (!this.isNpc(actor) || npc.kit === undefined || npc.professionalRating === undefined)
+            return;
+        let roster = this.kitRoster.get(npc.kit);
+        if (!roster) {
+            roster = new Set();
+            this.kitRoster.set(npc.kit, roster);
+        }
+        roster.add(npc.name);
+        // p.380: "a team of grunts has a Group Edge equal to its Professional
+        // Rating". p.380-381: a lieutenant "adds 1 to their Edge". Seeded once;
+        // a lieutenant who joins late tops it up by their one point.
+        if (!this.groupEdge.has(npc.kit)) {
+            this.groupEdge.set(npc.kit, groupEdgeFor(npc.professionalRating));
+        }
+        if (npc.lieutenant)
+            this.groupEdge.set(npc.kit, (this.groupEdge.get(npc.kit) ?? 0) + 1);
+    }
+    /**
+     * THE STATE OF A GRUNT'S TEAM, for the brain's morale check. Casualties
+     * are rostered names that are dead (gone from the scene), incapacitated
+     * or death-claimed; a grunt who surrendered still stands and is not
+     * one. The lieutenant's +1 to PR lasts only while the lieutenant does.
+     */
+    teamOf(npc) {
+        if (npc.kit === undefined || npc.professionalRating === undefined)
+            return undefined;
+        const roster = this.kitRoster.get(npc.kit);
+        if (!roster)
+            return undefined;
+        let casualties = 0;
+        let lieutenantStands = false;
+        for (const name of roster) {
+            const member = this.scene.getActor(name);
+            const down = !member || member.isIncapacitated() || member.deathClaimed;
+            if (down)
+                casualties++;
+            else if (member.lieutenant)
+                lieutenantStands = true;
+        }
+        return {
+            kit: npc.kit,
+            total: roster.size,
+            casualties,
+            effectivePr: npc.professionalRating + (lieutenantStands ? 1 : 0),
+            edge: this.groupEdge.get(npc.kit) ?? 0,
+        };
+    }
+    /**
+     * SPEND A POINT OF GROUP EDGE ON THIS GRUNT (p.380: "the gamemaster
+     * can spend a point of Group Edge on any grunt on the team"). The
+     * engine is the gamemaster, and its standing policy is the plain one:
+     * one point per grunt per fight, on that grunt's first attack, while
+     * the pool lasts. Arms the same boost a runner's "edge" verb arms
+     * (Player.consumeEdgeBoost adds `edge` dice to the next strike), so
+     * the spend goes through the one lane every edge boost already uses.
+     */
+    spendGroupEdge(npc) {
+        if (npc.kit === undefined || npc.edgeBoostArmed || this.edgeSpentBy.has(npc.name))
+            return false;
+        const pool = this.groupEdge.get(npc.kit) ?? 0;
+        if (pool <= 0)
+            return false;
+        this.groupEdge.set(npc.kit, pool - 1);
+        this.edgeSpentBy.add(npc.name);
+        npc.edgeBoostArmed = true;
+        this.logger.write(`Encounter: Group Edge spent on ${npc.name} (${npc.kit}: ${pool - 1} left).`);
+        return true;
+    }
     /**
      * Someone walks into a running fight (p.160 Changing Initiative):
      * roll as normal, minus 10 per pass already gone this turn.

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

@@ -72,6 +72,11 @@ const roundTo5 = (n) => Math.max(5, Math.round(n / 5) * 5);
  * 120-nuyen credstick selling for its 25-nuyen shell prints money. */
 export function priceOf(item) {
     const cash = item.isCurrencyCarrier() ? item.currencyAmount : 0;
+    // Armor that stopped the rounds that killed its wearer is not a
+    // trade good (Room.layOutBody): a fence pays for the plates, and the
+    // plates are what is gone.
+    if (item.ruined)
+        return cash;
     if (typeof item.price === 'number' && item.price > 0)
         return Math.round(item.price) + cash;
     const base = CATEGORY_BASE[item.category] ?? 50;

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

@@ -3,6 +3,7 @@ import { Logger } from './logger.js';
 import { CommandRegistry } from '../commands/command-registry.js';
 import { actorCell, actorDistanceMeters, standingRoomNear, ADJACENT_METERS } from './spots.js';
 import { METERS_PER_CELL } from './room-grid.js';
+import { outfitNpcBySlug, equipKitIntoHands } from '../npc-kits.js';
 /**
  * Bring one into the world. Returns the NPC, or null when the name is
  * already taken -- the same refusal spawnCompanionShell makes, and for
@@ -17,9 +18,11 @@ export function spawnEphemeral(host, opts) {
     const npc = new NPC({
         dialog: [],
         description: opts.description,
-        playerConstructorConfig: { playerName: opts.name, startLocation: opts.room, combat: opts.combat },
+        playerConstructorConfig: { playerName: opts.name, startLocation: opts.room, combat: opts.combat ?? {} },
     }, new CommandRegistry(host.scene));
     npc.plane = 'meat';
+    if (outfitNpcBySlug(npc, opts.kit))
+        equipKitIntoHands(npc);
     // 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.
@@ -62,8 +65,19 @@ export function despawnEphemerals(host, opts) {
                 : opts.playerRoomName !== undefined && opts.playerRoomName !== mark.roomName;
         if (!ended)
             continue;
-        if (host.scene.getActor(name) instanceof NPC)
-            host.scene.removeActor(name);
+        const body = host.scene.getActor(name);
+        // A DEPARTURE IS NOT A DEATH (2026-09-15, the day kits gave gangers
+        // a Browning and an armor vest). removeActor spills what an actor
+        // carried onto the floor, which is right for a corpse and wrong for
+        // a ganger who watched you walk off their corner: the street was
+        // raining pistols, per ganger, per block. A body that is DOWN when
+        // its scope ends spills, because it is a body; one that simply
+        // stops existing takes its gear with it. That is also the honest
+        // reading of this governor's founding denial -- an ephemeral
+        // cannot create obligations, and a gun the world must keep track
+        // of after its owner is gone is one.
+        if (body instanceof NPC)
+            host.scene.removeActor(name, { spill: body.isIncapacitated() });
         host.ephemerals.delete(name);
         removed.push(name);
     }

package/bundle/typescript/src/commands/game/sideQuest/utilities/npc-combat-brain.js

@@ -2,6 +2,7 @@ import { Category } from '../types/shared/item-enum.js';
 import { inMeleeReach, isInCover, coverAvailableFor, actorDistanceMeters } from './spots.js';
 import { Logger } from './logger.js';
 import { runIcActionPhase } from './ic-brain.js';
+import { moraleBandFor, moraleBreakLine, moraleBreaks } from '../npc-kits.js';
 /**
  * AN NPC'S ACTION PHASE, PLAYED BY RULE (SR5 p.163-167).
  *
@@ -54,6 +55,27 @@ export async function runNpcActionPhase(enc, npc) {
         tell(`${npc.name} looks for a target and finds none.`);
         return;
     }
+    // MORALE (SR5 p.379-380, npc-kits.ts moraleBreaks): a team of grunts
+    // breaks at the book's casualty thresholds -- untrained when one
+    // drops, semi-trained past a quarter, trained past half, elite never.
+    // THE VERB IS SURRENDER where the book says flee / retreat / withdraw:
+    // this engine's one primitive for "stops fighting without dying" is
+    // `surrender`, and it carries the consequence the book intends -- the
+    // fight ends cleanly, no parting shot, and the pair drops out of
+    // stillHostile(). A grunt sent through `go` instead would stand in the
+    // next room still hostile and still on the contact ladder, which is
+    // the opposite of having broken. The THRESHOLD is canon; only the word
+    // is the engine's. Without this, a kitted ganger who fights to the
+    // death is a harder, longer, less canon fight than a naked one.
+    const team = enc.teamOf(npc);
+    if (team && moraleBreaks(team.effectivePr, team.casualties, team.total)) {
+        const r = await npc.actInCombat('surrender');
+        logger.write(`Brain: ${npc.name} morale breaks (${team.kit}: ${team.casualties}/${team.total} down, PR ${team.effectivePr}) -> ${r}`);
+        if (npc.surrendered) {
+            tell(moraleBreakLine(npc.name, moraleBandFor(team.effectivePr)));
+            return;
+        }
+    }
     const target = pickTarget(npc, enemies);
     npc.combatOpponent = target;
     npc.lastExchangeAt = Date.now();
@@ -109,6 +131,7 @@ export async function runNpcActionPhase(enc, npc) {
             }
             const b = enc.budgetOf(npc);
             if (b?.complexAvailable) {
+                spendGroupEdge(enc, npc, tell);
                 const r = await npc.actInCombat(`attack ${target.name}`);
                 logger.write(`Brain: ${npc.name} attack ${target.name} -> ${r.split('\n')[0]}`);
                 if (!enc.budgetOf(npc)?.attackTaken)
@@ -126,6 +149,7 @@ export async function runNpcActionPhase(enc, npc) {
             continue;
         }
         if (!budget.attackTaken && budget.simple >= 1) {
+            spendGroupEdge(enc, npc, tell);
             const r = await npc.actInCombat(`attack ${target.name}`);
             logger.write(`Brain: ${npc.name} attack ${target.name} -> ${r.split('\n')[0]}`);
             if (!enc.budgetOf(npc)?.attackTaken) {
@@ -139,6 +163,18 @@ export async function runNpcActionPhase(enc, npc) {
         return;
     }
 }
+/**
+ * GROUP EDGE (SR5 p.380): the gamemaster spends the team's pool on a
+ * grunt about to strike. The engine is the gamemaster; the policy is
+ * CombatEncounter.spendGroupEdge's. One line to the room when it lands,
+ * so the runner knows why that shot rolled hot.
+ */
+function spendGroupEdge(enc, npc, tell) {
+    if (npc.kit === undefined)
+        return;
+    if (enc.spendGroupEdge(npc))
+        tell(`${npc.name} digs deep.`);
+}
 /** The opponent already engaged, else the nearest of the rest. */
 function pickTarget(npc, enemies) {
     const engaged = npc.combatOpponent;

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

@@ -184,6 +184,8 @@ export function serializeItem(item) {
         out.revealedTo = [...item.revealedTo];
     if (item.isCyberdeck() && item.deckOrder.join() !== '0,1,2,3')
         out.deckOrder = item.deckOrder;
+    if (item.ruined)
+        out.ruined = true;
     return out;
 }
 /** Mirrors ItemFactory.createItemFromJson (synchronously), then lays
@@ -223,6 +225,8 @@ export function restoreItem(json) {
         item.jammed = true;
     if (json.bricked)
         item.bricked = true;
+    if (json.ruined)
+        item.ruined = true;
     if (json.deckDamage)
         item.takeDeckDamage(json.deckDamage);
     if (json.droneDamage)

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

@@ -174,9 +174,17 @@ function postSweepOfficer(game, room, band) {
         // not follow.
         until: 'exchange',
         room,
-        // A working rent-a-cop, not a boss fight. Deliberately ordinary:
-        // the player who decides to swing at security should be picking a
-        // fight with a person, not a set piece.
+        // PROFESSIONAL RATING 3, "Police Patrols" (SR5 p.383): the catalog's
+        // `police-patrol` npc-kit row -- armor jacket, Ares Predator V,
+        // Defiance EX Shocker, stun baton, Renraku Sensei, and a Biometric
+        // Reader (p.440), which is what the book has where this prose says
+        // "wand" -- SR5 prints no such item. factionOf() already read an
+        // 'authority' ephemeral as Knight Errant; the row says so too.
+        // A working beat cop, not a boss fight: the player who decides to
+        // swing at one is picking a fight with a person, not a set piece.
+        kit: SWEEP_OFFICER_KIT,
+        // A pre-v21 cache resolves to no kit and gets this instead: the old
+        // rent-a-cop numbers, exactly as before.
         combat: {
             body: 3, agility: 3, reaction: 3, strength: 3, willpower: 3,
             logic: 3, intuition: 3, charisma: 3, edge: 1, combatSkill: 3,
@@ -184,6 +192,8 @@ function postSweepOfficer(game, room, band) {
         },
     });
 }
+/** The sweep officer's npc-kit row (npc-kits.ts). */
+export const SWEEP_OFFICER_KIT = 'police-patrol';
 /**
  * THE OFFICERS, and there is more than one of them now.
  *