@maka/maka-cli 5.91.0 → 5.92.0

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

@@ -49,6 +49,16 @@ export default class Game {
     private _logBox;
     private _metaBox;
     private _quitArmed;
+    /**
+     * The quit verb already sealed this runner to the grid, so the
+     * process-exit hook has nothing left to do. Set ONLY after an awaited
+     * flush -- an optimistic set would make the exit hook skip the spill
+     * write on a push that never landed, which is the one way this design
+     * can silently lose a beat. (Mutation-checked: never setting it is
+     * caught, and so is setting it without the flush.)
+     */
+    private _quitSealed;
+    get quitSealed(): boolean;
     private _escArmedAt;
     private _statusBox;
     /** The clock gutter left of the prompt, its ticker, and the face it
@@ -937,15 +947,63 @@ export default class Game {
      * and snapshotVendorStock (both deliberately pre-overlay).
      */
     private applyResumeState;
+    /**
+     * IS THIS RUNNER'S LIFE THE SERVER'S? (server-only storage.)
+     *
+     * A bound runner has an account behind them; an anonymous one never
+     * leaves this machine, and a bench is a scratch session with nothing
+     * worth keeping. Every new branch in the save path gates on this, so
+     * the anonymous route is the code that was already here -- which is
+     * what the unmodified tripwire suites prove.
+     */
+    private get boundRunner();
+    /** Where this runner's crash journal lives, when they are bound. */
+    private get spillPath();
     /**
      * THE single save routine -- every safe beat funnels here. Guards make
      * it a silent no-op anywhere a save would lie: mid-run (the "runs are
      * disposable" ruling lives in the scene === _hubScene check), downed
-     * or KO'd, mid-exchange, dead, or before init finishes. Synchronous by
-     * design so the process-exit quit hook can use it; failures log and
-     * never crash a turn.
+     * or KO'd, mid-exchange, dead, or before init finishes.
+     *
+     * SYNCHRONOUS BY DESIGN, AND FOR TWO DIFFERENT REASONS NOW. It always
+     * had to be, because `process.on('exit')` can run nothing
+     * asynchronous. For a BOUND runner that same constraint is what makes
+     * the spill the durability guarantee rather than the push: the beat
+     * writes `<slug>.spill` synchronously and returns, and the upload
+     * happens behind it on a queue that may never get the chance to
+     * finish. Nothing here awaits the grid, ever -- a save beat that could
+     * block on a network is a turn that can hang.
+     *
+     * PR1 KEEPS WRITING `<slug>.json` FOR BOUND RUNNERS TOO. That is
+     * deliberate and temporary: this PR is a superset of today's
+     * behaviour, so reverting it strands no data and loses no character.
+     * PR2 is where the bound branch stops writing the local slot, once
+     * the server contract is deployed and the launcher can source the menu
+     * from it.
      */
     requestSave(reason: SaveReason): void;
+    /**
+     * SEAL A BOUND RUNNER TO THE GRID -- the awaited counterpart of
+     * requestSave, for the two beats where "eventually" is a bug.
+     *
+     *   QUIT: nothing runs after this process. An unpushed beat is not
+     *   "late", it is gone until the next launch sweeps the spill -- and
+     *   the player was told their game was saved.
+     *
+     *   JOB ACCEPT: the shared run loads this character FROM THE SERVER.
+     *   An unpushed beat means the table plays a stale snapshot of them,
+     *   which is a real bug today (the unawaited push before shared runs)
+     *   and closes here for free.
+     *
+     * Returns true when the server has the newest save. FALSE IS NOT A
+     * FAILURE PATH -- it means the spill stands and the next launch
+     * uploads it, which is ruling 2 working exactly as designed. Callers
+     * report, they do not block the player.
+     *
+     * Anonymous and bench runners return true immediately: they have
+     * nothing to seal and must never be made to wait on a network.
+     */
+    flushBoundSave(reason: SaveReason): Promise<boolean>;
     private buildSaveFile;
     /**
      * Synchronous readiness check for continueToNextScene() -- lets callers
@@ -1358,6 +1416,40 @@ export default class Game {
      * utilities/ephemeral.ts decides what each kind does with its beat;
      * this only carries the narration back. Only a mob ever produces any.
      */
+    /** One beat in flight at a time (see utilities/alarmed-staff.ts). */
+    private _alarmBeat;
+    /**
+     * THE ALARMED SITE'S TURN, hung off the same single dispatch the host's
+     * and the ephemerals' are -- one player action is one beat for the
+     * people who work here.
+     *
+     * AN ENGINE MAPPING, NOT A RULE, in exactly the sense withICTurn says
+     * it: SR5 writes no general mechanics for how guards react to an alarm
+     * (asked twice, two wordings, same answer), and p.352's "delay the
+     * runner team" is conditioned on an HTR team being en route, which in
+     * a Zone 0 barrens it never is. Nothing here invents a response table,
+     * a convergence rate or an aggression dial. What changed is only this:
+     * NPC.act()'s two callers both live inside respondTo(), so a scene NPC
+     * was mute unless the player addressed it. The engine stops muzzling
+     * them while a site is alarmed. What any of them DOES with a beat is
+     * the judgment it already exercises when spoken to.
+     *
+     * IT APPENDS NOTHING, and that is worth saying because it makes the
+     * one thing this wrapper's POSITION was chosen for moot. The seam
+     * agreement put this inner to withEphemeralTurn so an alarmed guard
+     * would print above somebody eating noodles -- sound reasoning for an
+     * appending wrapper, and irrelevant to a fire-and-forget one that
+     * returns `result` untouched. The position is kept as agreed so the
+     * slot exists if this ever narrates inline; the ordering argument is
+     * recorded as not currently biting rather than quietly inherited.
+     *
+     * FIRE AND FORGET on the player's own ruling, offered three shapes:
+     * reactions "arrive a moment later" while play continues at full
+     * speed, one in flight so they never pile up. The precedent is
+     * draftNextSceneInBackground -- never make the player wait on a model
+     * call.
+     */
+    private withAlarmTurn;
     private withEphemeralTurn;
     private withICTurn;
     /**

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

@@ -7,14 +7,15 @@ import { Item } from './models/item.js';
 import { Room } from './models/_index.js';
 import { Door } from './models/door.js';
 import { SAVE_VERSION } from './types/save-file.js';
-import { serializePlayer, restorePlayer, captureHubOverlay, applyHubOverlay, writeSaveAtomic, deleteSave, restoreItem, readSave, serializeItem, saveSlug, } from './utilities/persistence.js';
+import { serializePlayer, restorePlayer, captureHubOverlay, applyHubOverlay, writeSaveAtomic, deleteSave, restoreItem, readSave, serializeItem, saveSlug, spillPathFor, } from './utilities/persistence.js';
 import { heartbeatPresence, heartbeatPresenceNow } from './utilities/social.js';
 import { presenceBeatAllowed } from './utilities/presence-gate.js';
-import { pushSave, burnCloudSaveFor } from './utilities/cloud-saves.js';
+import { pushSave, burnCloudSaveFor, enqueueBoundPush, flushPushQueue, writeSpill, clearSpill, hasPendingPush, } from './utilities/cloud-saves.js';
 import { DOCWAGON_TIERS, RESUSC_FEE, DEATH_COMP } from './utilities/docwagon.js';
 import { isFence, LIFESTYLE_TIERS } from './utilities/commerce.js';
 import { bestFakeSin, wandRead, processArrest } from './utilities/sin.js';
 import { tickEphemerals } from './utilities/ephemeral.js';
+import { requestAlarmBeat, newAlarmBeatLatch, ALARM_STIMULUS } from './utilities/alarmed-staff.js';
 import { renderMapViewport, mapCaption } from './utilities/map-view.js';
 import { tallestRoomRows } from './utilities/room-grid.js';
 import { renderRoomLayoutCompact, crewOfTable, roomCaption } from './utilities/room-view.js';
@@ -179,6 +180,16 @@ export default class Game {
     // Quit confirmation state (see handleInput / initInputBox): armed by
     // the first quit/exit or ESC, cleared by anything that isn't a yes.
     _quitArmed = false;
+    /**
+     * The quit verb already sealed this runner to the grid, so the
+     * process-exit hook has nothing left to do. Set ONLY after an awaited
+     * flush -- an optimistic set would make the exit hook skip the spill
+     * write on a push that never landed, which is the one way this design
+     * can silently lose a beat. (Mutation-checked: never setting it is
+     * caught, and so is setting it without the flush.)
+     */
+    _quitSealed = false;
+    get quitSealed() { return this._quitSealed; }
     _escArmedAt = 0;
     _statusBox;
     /** The clock gutter left of the prompt, its ticker, and the face it
@@ -2872,13 +2883,45 @@ ${client.name} won't be remembering anything. Dead Johnsons pay nothing -- and t
         this.refreshLogLabel();
         Logger.getInstance().write(`Resumed save for ${save.playerName} (saved ${save.savedAt}, reason ${save.reason}).`);
     }
+    /**
+     * IS THIS RUNNER'S LIFE THE SERVER'S? (server-only storage.)
+     *
+     * A bound runner has an account behind them; an anonymous one never
+     * leaves this machine, and a bench is a scratch session with nothing
+     * worth keeping. Every new branch in the save path gates on this, so
+     * the anonymous route is the code that was already here -- which is
+     * what the unmodified tripwire suites prove.
+     */
+    get boundRunner() {
+        return !this._anonymous && !this._bench && !!this._owner;
+    }
+    /** Where this runner's crash journal lives, when they are bound. */
+    get spillPath() {
+        if (!this._saveFilePath || !this.boundRunner)
+            return undefined;
+        return spillPathFor(dirname(this._saveFilePath), this.player.name);
+    }
     /**
      * THE single save routine -- every safe beat funnels here. Guards make
      * it a silent no-op anywhere a save would lie: mid-run (the "runs are
      * disposable" ruling lives in the scene === _hubScene check), downed
-     * or KO'd, mid-exchange, dead, or before init finishes. Synchronous by
-     * design so the process-exit quit hook can use it; failures log and
-     * never crash a turn.
+     * or KO'd, mid-exchange, dead, or before init finishes.
+     *
+     * SYNCHRONOUS BY DESIGN, AND FOR TWO DIFFERENT REASONS NOW. It always
+     * had to be, because `process.on('exit')` can run nothing
+     * asynchronous. For a BOUND runner that same constraint is what makes
+     * the spill the durability guarantee rather than the push: the beat
+     * writes `<slug>.spill` synchronously and returns, and the upload
+     * happens behind it on a queue that may never get the chance to
+     * finish. Nothing here awaits the grid, ever -- a save beat that could
+     * block on a network is a turn that can hang.
+     *
+     * PR1 KEEPS WRITING `<slug>.json` FOR BOUND RUNNERS TOO. That is
+     * deliberate and temporary: this PR is a superset of today's
+     * behaviour, so reverting it strands no data and loses no character.
+     * PR2 is where the bound branch stops writing the local slot, once
+     * the server contract is deployed and the launcher can source the menu
+     * from it.
      */
     requestSave(reason) {
         const logger = Logger.getInstance();
@@ -2903,17 +2946,74 @@ ${client.name} won't be remembering anything. Dead Johnsons pay nothing -- and t
                 save.sync = prev.save.sync;
             writeSaveAtomic(this._saveFilePath, save);
             logger.write(`Saved (${reason}) -> ${this._saveFilePath}`);
-            // Local-first: the beat is DONE the moment the file lands. The
-            // cloud mirror rides behind, fire-and-forget (see cloud-saves.ts
-            // -- logged-out/offline/expired all degrade to a silent no-op).
-            // An ANONYMOUS runner's life never leaves this machine.
-            if (!this._anonymous)
-                void pushSave(this._saveFilePath, save);
+            // An ANONYMOUS runner's life never leaves this machine, and this
+            // is where that stays true: no spill, no queue, no request.
+            if (this._anonymous)
+                return;
+            const spill = this.spillPath;
+            if (spill) {
+                // THE JOURNAL, WRITTEN BEFORE THE PUSH IS EVEN ATTEMPTED. If the
+                // grid is down -- or the process dies in the next millisecond --
+                // this file is the beat. Ordering matters: enqueueing first and
+                // spilling second would leave a window where a crash loses a
+                // beat that a confirmed push had not yet covered.
+                writeSpill(spill, save);
+                enqueueBoundPush(this._saveFilePath, save, spill);
+                return;
+            }
+            // Legacy/unbound-but-not-anonymous: the pre-existing mirror, still
+            // fire-and-forget (cloud-saves.ts -- logged-out, offline and
+            // expired all degrade to a silent no-op).
+            void pushSave(this._saveFilePath, save);
         }
         catch (err) {
             logger.error(`requestSave(${reason}) failed: ${err}`);
         }
     }
+    /**
+     * SEAL A BOUND RUNNER TO THE GRID -- the awaited counterpart of
+     * requestSave, for the two beats where "eventually" is a bug.
+     *
+     *   QUIT: nothing runs after this process. An unpushed beat is not
+     *   "late", it is gone until the next launch sweeps the spill -- and
+     *   the player was told their game was saved.
+     *
+     *   JOB ACCEPT: the shared run loads this character FROM THE SERVER.
+     *   An unpushed beat means the table plays a stale snapshot of them,
+     *   which is a real bug today (the unawaited push before shared runs)
+     *   and closes here for free.
+     *
+     * Returns true when the server has the newest save. FALSE IS NOT A
+     * FAILURE PATH -- it means the spill stands and the next launch
+     * uploads it, which is ruling 2 working exactly as designed. Callers
+     * report, they do not block the player.
+     *
+     * Anonymous and bench runners return true immediately: they have
+     * nothing to seal and must never be made to wait on a network.
+     */
+    async flushBoundSave(reason) {
+        if (!this.boundRunner)
+            return true;
+        // Take a final beat first, so the thing we seal is the state the
+        // player is quitting FROM rather than whatever the last autosave
+        // happened to catch.
+        this.requestSave(reason);
+        if (!hasPendingPush())
+            return true;
+        const sealed = await flushPushQueue();
+        if (sealed) {
+            const spill = this.spillPath;
+            // The queue clears the spill on a confirmed push; this is the
+            // belt for the case where the confirmation raced the final beat.
+            if (spill) {
+                const current = readSave(this._saveFilePath);
+                if (current.ok)
+                    clearSpill(spill, current.save.savedAt);
+            }
+        }
+        Logger.getInstance().write(`flushBoundSave(${reason}): ${sealed ? 'sealed' : 'left in the spill'}.`);
+        return sealed;
+    }
     buildSaveFile(reason) {
         return {
             version: SAVE_VERSION,
@@ -3865,7 +3965,12 @@ ${client.name} won't be remembering anything. Dead Johnsons pay nothing -- and t
         // session's homecoming hands back to it.
         if (this.pendingSharedRun) {
             const { sessionID } = this.pendingSharedRun;
-            this.requestSave('job-accept');
+            // AWAITED, unlike the solo departure below, because the shared
+            // session loads this character FROM THE SERVER. A fire-and-forget
+            // push here is the known stale-snapshot race: the table starts
+            // playing a version of you that predates the beat you just took.
+            // For an anonymous or unbound runner this returns immediately.
+            await this.flushBoundSave('job-accept');
             try {
                 const { SharedRunSession } = await import('./utilities/shared-run.js');
                 const banner = await SharedRunSession.startAsLeader(this, sessionID);
@@ -3888,6 +3993,12 @@ ${client.name} won't be remembering anything. Dead Johnsons pay nothing -- and t
         }
         // The departure save: hub state with the job still on offer -- what
         // a mid-run quit resumes to (the "runs are disposable" ruling).
+        //
+        // NOT awaited, unlike the shared-run branch above, and the asymmetry
+        // is deliberate: nothing loads this save from the server on a solo
+        // run, so there is no stale-snapshot race to close -- and awaiting a
+        // push here would put a network round trip (up to TIMEOUT_MS) in
+        // front of every departure for no gain. The spill covers the crash.
         this.requestSave('job-accept');
         // CARRY THE OFFER'S HAGGLE ACROSS THE TRAVEL, BUT ONLY THIS
         // OFFER'S (d4yoYPcRAtWpLtm9y: "I got a notice that I've already
@@ -4992,6 +5103,29 @@ ${client.name} won't be remembering anything. Dead Johnsons pay nothing -- and t
         if (this._quitArmed) {
             this._quitArmed = false;
             if (/^(y|yes|quit|exit)$/i.test(verb)) {
+                // THE SEAL. This is the last moment anything asynchronous can
+                // run for this character -- ui.ts turns a null response into
+                // process.exit(0), and the exit hook that follows can only write
+                // the spill. So a bound runner's final beat is pushed HERE,
+                // awaited, or it does not get pushed at all.
+                //
+                // The player is told, because a quit that pauses for a network
+                // round trip with no explanation reads as a hang.
+                if (this.boundRunner) {
+                    const logger = Logger.getInstance();
+                    logger.logWithColor(`Sealing your save to the grid...`, 'cyan');
+                    this._screen?.render();
+                    const sealed = await this.flushBoundSave('quit');
+                    if (!sealed) {
+                        // NOT an error, and worded so it does not read as one: the
+                        // spill is on disk and the next launch uploads it. Saying
+                        // nothing here would be the actual failure -- the player
+                        // would believe their evening reached the server.
+                        logger.logWithColor(`The grid didn't answer -- your progress is saved on this machine and will upload next launch.`, 'yellow');
+                        this._screen?.render();
+                    }
+                    this._quitSealed = true;
+                }
                 return out(null);
             }
             // fall through -- the answer was a real command; play on.
@@ -5042,7 +5176,7 @@ ${client.name} won't be remembering anything. Dead Johnsons pay nothing -- and t
         const command = CommandFactory.createCommand(verb, context);
         if (command) {
             const result = await command.execute(args);
-            return out(this.withEphemeralTurn(actor, this.withICTurn(actor, result)));
+            return out(this.withEphemeralTurn(actor, this.withAlarmTurn(actor, this.withICTurn(actor, result))));
         }
         // Typo tolerance: two straight sessions bounced on slips like "searh"
         // and "maop". Reuse the same fuzzy matcher item/NPC names go through
@@ -5101,6 +5235,50 @@ ${client.name} won't be remembering anything. Dead Johnsons pay nothing -- and t
      * utilities/ephemeral.ts decides what each kind does with its beat;
      * this only carries the narration back. Only a mob ever produces any.
      */
+    /** One beat in flight at a time (see utilities/alarmed-staff.ts). */
+    _alarmBeat = newAlarmBeatLatch();
+    /**
+     * THE ALARMED SITE'S TURN, hung off the same single dispatch the host's
+     * and the ephemerals' are -- one player action is one beat for the
+     * people who work here.
+     *
+     * AN ENGINE MAPPING, NOT A RULE, in exactly the sense withICTurn says
+     * it: SR5 writes no general mechanics for how guards react to an alarm
+     * (asked twice, two wordings, same answer), and p.352's "delay the
+     * runner team" is conditioned on an HTR team being en route, which in
+     * a Zone 0 barrens it never is. Nothing here invents a response table,
+     * a convergence rate or an aggression dial. What changed is only this:
+     * NPC.act()'s two callers both live inside respondTo(), so a scene NPC
+     * was mute unless the player addressed it. The engine stops muzzling
+     * them while a site is alarmed. What any of them DOES with a beat is
+     * the judgment it already exercises when spoken to.
+     *
+     * IT APPENDS NOTHING, and that is worth saying because it makes the
+     * one thing this wrapper's POSITION was chosen for moot. The seam
+     * agreement put this inner to withEphemeralTurn so an alarmed guard
+     * would print above somebody eating noodles -- sound reasoning for an
+     * appending wrapper, and irrelevant to a fire-and-forget one that
+     * returns `result` untouched. The position is kept as agreed so the
+     * slot exists if this ever narrates inline; the ordering argument is
+     * recorded as not currently biting rather than quietly inherited.
+     *
+     * FIRE AND FORGET on the player's own ruling, offered three shapes:
+     * reactions "arrive a moment later" while play continues at full
+     * speed, one in flight so they never pile up. The precedent is
+     * draftNextSceneInBackground -- never make the player wait on a model
+     * call.
+     */
+    withAlarmTurn(actor, result) {
+        if (result === null)
+            return null;
+        // The primary's actions drive the site. A second human's commands
+        // arrive through the same dispatch, and two humans each triggering a
+        // beat would double the site's voice without doubling the site.
+        if (actor !== this.player)
+            return result;
+        requestAlarmBeat(this._alarmBeat, this.scene, actor, npc => npc.respondTo(actor, ALARM_STIMULUS));
+        return result;
+    }
     withEphemeralTurn(actor, result) {
         if (result === null)
             return null;