Connect Emperor Nexus extra revival with private saved continuation

Add the absent-Emperor Secret Ally alternative returning exactly three eligible forces free in Basic/Advanced base-faction Nexus games. Preserve ordinary force/free-revival allowances and the shared Advanced Fedaykin cap. Keep the action optional and private, consume the physical Nexus once, and validate durable source receipts through later ordinary revival and Ghola. Purchase timing remains pending the earlier uniform winner-payment UX question; partial returns and combined-module interactions remain guarded. No mode or publication gate opens.

Connect private controls, explicit physical elite selection, all four legal AI profiles and a dedicated rules checklist entry. Extend the reusable local prototype writer with genuine twelve-card Nexus setup. Independent review covers rules timing, private projection, physical custody, JSON and production SQLite restore, lost-response replay and competing requests. Seventeen focused effect cases and four prototype-writer cases pass.

Validation: typecheck, lint, 4649 offline tests, production build and 43 HTTP tests passed with unchanged source. Genuine-start Basic and Advanced samples completed in 715 and 263 actions with 19 and 7 periodic JSON restores, respectively, and no Emperor uses. Two explicitly staged continuations completed in 18 and 17 actions with one normal-force Emperor return each. All four had zero rejections and preserved exact Treachery, force, elite and Nexus custody; all fourteen final seat views restored unchanged. They are bounded continuation evidence, not natural full-game acceptance of the effect or AI calibration.

In the conserved staged browser scenario, Advanced Fremen returned three forces including one Fedaykin using the Nexus, then three normal forces using the ordinary allowance. Reserves rose from three to nine, Tanks fell from seven to one, spice stayed three and the physical Nexus was spent once. The inspector was readable, the action notice displayed, and pending/resolved refresh restoration, physical custody and private projection passed.

After the reported power outage, all 733 opening games and original seat/recovery records were preserved (767 after HTTP checks); database integrity and foreign keys passed. All 734 rooms immediately before broad verification remained unchanged. Reused the healthy server without restart, reset or recurring automation.

Verified source tree: fd09a4bc71018cb7ef98c7e25c25dacc495ffed304dbd0cdfa223e539e8fa5e1

game/bots.ts

@@ -70,6 +70,7 @@ import { quoteSmugglerShipment } from './smuggler-shipment';
 import { quoteSmugglerNoField } from './smuggler-no-field';
 import { spiceBankerBattleMaximum, spiceBankerModeSupported } from './spice-banker';
 import { nexusGuildSecretAllyAction, nexusGuildSecretAllyCanAct, nexusGuildSecretAllyQuote } from './nexus-guild-secret-ally-options';
+import { nexusEmperorRevivalAction } from './nexus-emperor-secret-ally-options';
 import { nexusRicheseAction, nexusRicheseQuote } from './nexus-richese-options';
 import { liveShipmentPromises, matchesShipment } from './shipment-promises';
 import {
@@ -3659,6 +3660,15 @@ function standaloneGholaAction(g: GameView, ordinary: Action[]): Action | null {
 
 /** Obligations apply across policy branches, including choosing to move first. */
 export function botActions(g: GameView): Action[] {
+  const emperorRevival = g.nexusEmperorSecretAlly?.revival;
+  if (emperorRevival && !emperorRevival.blocked && emperorRevival.eliteOptions.length) {
+    const own = g.players.find((player) => player.id === g.me);
+    const elite = own?.bot === 'Easy'
+      ? Math.min(...emperorRevival.eliteOptions)
+      : Math.max(...emperorRevival.eliteOptions);
+    const action = nexusEmperorRevivalAction(g, elite);
+    if (action) return [action];
+  }
   const bureaucrat = g.bureaucrat?.pending;
   if (bureaucrat) {
     if (bureaucrat.owner !== g.me || g.decision?.kind !== 'bureaucratPayment' ||

game/engine.ts

@@ -26,6 +26,7 @@ import { createDiscoveryState, validateDiscoveryState, placeDiscovery, rememberD
 import { quoteJacurutuBattleIncome } from './discovery-battle';
 import { greatMakerSignature, greatMakerMajority, validateGreatMaker, type GreatMaker } from './great-maker';
 import { quoteNexusChoamTrade, validateNexusChoamTrade, nexusChoamTradeSignature, type NexusChoamTrade } from './nexus-choam-trade';
+import { EMPEROR_NEXUS_REVIVALS, emperorNexusEvent, emperorNexusSignature, emperorNexusModeSupported, emperorNexusPools, emperorNexusRevivalElites, validateEmperorNexusRevival, type NexusEmperorRevival } from './nexus-emperor-secret-ally';
 import { createNexusGuildSecretAlly, validateNexusGuildSecretAlly, quoteNexusGuildSecretShipment, type NexusGuildSecretAllyReceipt } from './nexus-guild-secret-ally';
 import { shipmentAvailable } from './shipment-opportunity';
 import { createNexusGuildCunning, validateNexusGuildCunning, nexusGuildCunningMoves, type NexusGuildCunningReceipt } from './nexus-guild-cunning';
@@ -975,6 +976,8 @@ export type Game = {
   greatMaker?: GreatMaker;
   nexusChoamTrades?: NexusChoamTrade[];
   nexusChoamTradeLast?: { event: string; stage: NexusChoamTrade['stage'] };
+  nexusEmperorSecretHistory?: NexusEmperorRevival[];
+  nexusEmperorSecretEvents?: string[];
   treacheryDiscardSequence?: number;
   resolvedTreacheryDiscardSequence?: number;
   /** Committed discard receipts are evidence, not additional card custody. */
@@ -1647,6 +1650,60 @@ function currentNexusChoamTrade(g: Game, owner: string) {
   return nexusRule(() => quoteNexusChoamTrade(g, owner,
     g.phase === 7 && grummanCollectionAutomatic(g)));
 }
+function nexusEmperorSecretAllyOffer(g:Game,owner:string) {
+  const p = g.players.find(p => p.id === owner);
+  if (!p || g.nexusCards?.cards?.hands[owner] !== 'emperor' || byFaction(g,'emperor')) return null;
+  const event = emperorNexusEvent(g.turn,g.phase,owner,g.nexusEmperorSecretHistory?.length ?? 0);
+  let blocked:string|null = null;
+  if (p.ally) blocked = 'Emperor Nexus Secret Ally requires an unallied holder.';
+  else if (!emperorNexusModeSupported(g)) blocked = 'Emperor Nexus Secret Ally currently requires base factions and Nexus alone; expansion and other module combinations remain pending.';
+  else if (g.status !== 'playing' || g.phase !== 4) blocked = 'Use the three-force Emperor Nexus return during Revival.';
+  else if (g.response || g.decision || g.truthtrance || g.phaseOpening || g.pendingRevival || g.pendingKarama ||
+    g.pendingTreacheryDiscard || g.pendingNullentropy || g.pendingExchange || g.pendingRicheseGift ||
+    g.pendingRichesePurchaseIncome || g.pendingAmbassador || g.pendingCapture || g.battle ||
+    g.nexusTraitorPending || g.nexusCards.phase?.stage === 'drawing') blocked = 'Finish the current interaction before using Emperor Nexus revival.';
+  else if ((g.revivalPrevention?.turn === g.turn && g.revivalPrevention.player === owner) || g.revivalRules?.freeBlocked?.includes(owner) ||
+    g.revivalRules?.expanded.includes(owner) || g.freeRevival.includes(owner))
+    blocked = 'Emperor Nexus revival with free-revival suppression or expanded revival effects remains pending.';
+  const eliteOptions = emperorNexusRevivalElites(p,g.advanced);
+  if (!blocked && !eliteOptions.length) blocked = 'Emperor Nexus needs exactly three eligible forces in Tanks; a smaller return remains pending.';
+  return {event,revival:{blocked,eliteOptions},purchase:null};
+}
+function nexusEmperorSecretIntegrity(g:Game) {
+  const history = g.nexusEmperorSecretHistory, events = g.nexusEmperorSecretEvents;
+  if (history === undefined) {
+    requireRule(events === undefined,'Emperor Nexus has lost its saved use history.'); return;
+  }
+  requireRule(g.nexusCards?.cards && emperorNexusModeSupported(g) && Array.isArray(history) && history.length > 0 &&
+    Array.isArray(events) && events.length === history.length && new Set(events).size === events.length,
+    'Emperor Nexus has lost its physical module or independent use markers.');
+  for (const [index,record] of history.entries()) {
+    nexusRule(() => validateEmperorNexusRevival(g,record));
+    requireRule(record.sequence === index && events[index] === record.event,
+      'Emperor Nexus has duplicated or reordered a completed use.');
+  }
+  const last = history.at(-1)!;
+  if (last.turn === g.turn) requireRule(g.nexusCards.cards.discard.includes('emperor'),
+    'Emperor Nexus has reopened its already spent physical card.');
+}
+function playNexusEmperorRevive(g:Game,p:Player,action:Action) {
+  const offer = nexusEmperorSecretAllyOffer(g,p.id);
+  requireRule(offer && !offer.revival.blocked && action.event === offer.event &&
+    Object.keys(action).sort().join(',') === 'elite,event,type' && offer.revival.eliteOptions.includes(action.elite as number),
+    offer?.revival.blocked ?? 'Choose the current Emperor Nexus revival and an eligible exact three-force group.');
+  const elite = action.elite as number, before = emperorNexusPools(p);
+  g.nexusCards!.cards = nexusRule(() => discardNexusCard(g.nexusCards!.cards!,p.id,g.players));
+  addRevivedReserves(g,p,EMPEROR_NEXUS_REVIVALS,elite); p.tanks -= EMPEROR_NEXUS_REVIVALS;
+  if (p.elites) {p.elites.tanks -= elite;p.elites.revived += elite;}
+  const record:NexusEmperorRevival = {kind:'revival',event:offer.event,owner:p.id,turn:g.turn,phase:4,
+    faction:p.faction,advanced:g.advanced,
+    sequence:g.nexusEmperorSecretHistory?.length ?? 0,elite,before,after:emperorNexusPools(p),signature:''};
+  record.signature = emperorNexusSignature(record);
+  (g.nexusEmperorSecretHistory ??= []).push(record);
+  (g.nexusEmperorSecretEvents ??= []).push(record.event);
+  log(g,`${p.name} spent Emperor Nexus Secret Ally to return three forces${elite ? `, including ${elite} Fedaykin` : ''} from Tanks to reserves for free. Ordinary force and free-revival allowances are unchanged.`,
+    {faction:p.faction,name:'Emperor Nexus revival'});
+}
 function playNexusChoamTrade(g: Game, p: Player, action: Action) {
   const offer = currentNexusChoamTrade(g, p.id);
   requireRule(Object.keys(action).every(key => ['type', 'event', 'card'].includes(key)) &&
@@ -13593,6 +13650,7 @@ function gholaOptions(g: Game, p: Player) {
 }
 function marketGholaIntegrity(g: Game) {
   nexusCardsIntegrity(g);
+  nexusEmperorSecretIntegrity(g);
   nexusTraitorIntegrity(g);
   nexusFaceDancerIntegrity(g);
   nexusSuboidIntegrity(g);
@@ -19972,6 +20030,7 @@ function applyActionInner(
   }
   if (t === 'discovery') { playDiscovery(g, p, action); return g; }
   if (t === 'nexusChoamTrade') { playNexusChoamTrade(g, p, action); return g; }
+  if (t === 'nexusEmperorRevive') { playNexusEmperorRevive(g,p,action); return g; }
   if (t === 'nexusAtreides') { playNexusAtreides(g, p, action); return g; }
   requireRule(
     !(
@@ -23646,6 +23705,7 @@ export function viewGame(state: Game, id: string) {
     greatMaker: g.greatMaker ? { event:g.greatMaker.event, turn:g.greatMaker.turn, stage:g.greatMaker.stage, votes:structuredClone(g.greatMaker.votes), order:[...g.greatMaker.order], ride:greatMakerRideOptions(g,id) } : null,
     nexusCards: projectedNexusCards(g, id),
     nexusChoamTrade: currentNexusChoamTrade(g, id),
+    nexusEmperorSecretAlly: nexusEmperorSecretAllyOffer(g,id),
     nexusMoritani: nexusMoritaniOffer(g,id),
     nexusRichese: nexusRicheseOffer(g,id),
     nexusGuildSecretAlly: nexusGuildSecretAllyOffer(g,id),

game/nexus-emperor-secret-ally-options.ts

@@ -0,0 +1,31 @@
+import type { Action, GameView } from './engine';
+
+/** Bind the current private offer without inspecting another player's cards. */
+export function nexusEmperorRevivalAction(
+  game: GameView,
+  elite: number,
+): Action | null {
+  const offer = game.nexusEmperorSecretAlly;
+  const owner = game.players.find((player) => player.id === game.me);
+  if (
+    !offer ||
+    !owner ||
+    owner.ally ||
+    game.nexusCards?.card !== 'emperor' ||
+    game.players.some((player) => player.faction === 'emperor') ||
+    game.status !== 'playing' ||
+    game.phase !== 4 ||
+    game.response ||
+    game.decision ||
+    game.truthtrance ||
+    game.phaseOpening ||
+    game.automaticContinuationPending ||
+    game.nexusCards.waiting.length ||
+    game.nexusTraitors?.pending ||
+    offer.revival.blocked ||
+    !Number.isSafeInteger(elite) ||
+    !offer.revival.eliteOptions.includes(elite)
+  )
+    return null;
+  return { type: 'nexusEmperorRevive', event: offer.event, elite };
+}

game/nexus-emperor-secret-ally.ts

@@ -0,0 +1,147 @@
+import type { Game, Player } from './engine';
+import { eliteRevivalRemaining } from './revival';
+
+export const EMPEROR_NEXUS_REVIVALS = 3;
+export type EmperorNexusPools = {
+  reserves: number;
+  tanks: number;
+  eliteReserves: number;
+  eliteTanks: number;
+  eliteRevived: number;
+  revived: number;
+  freeForcesRevived: number | null;
+  spice: number;
+};
+export type NexusEmperorRevival = {
+  kind: 'revival';
+  event: string;
+  owner: string;
+  turn: number;
+  phase: 4;
+  sequence: number;
+  faction: Player['faction'];
+  advanced: boolean;
+  elite: number;
+  before: EmperorNexusPools;
+  after: EmperorNexusPools;
+  signature: string;
+};
+export function emperorNexusPools(p: Player): EmperorNexusPools {
+  return {
+    reserves: p.reserves,
+    tanks: p.tanks,
+    eliteReserves: p.elites?.reserves ?? 0,
+    eliteTanks: p.elites?.tanks ?? 0,
+    eliteRevived: p.elites?.revived ?? 0,
+    revived: p.revived,
+    freeForcesRevived: p.freeForcesRevived ?? null,
+    spice: p.spice,
+  };
+}
+export function emperorNexusEvent(
+  turn: number,
+  phase: number,
+  owner: string,
+  sequence: number,
+): string {
+  return JSON.stringify([
+    'nexusEmperorSecretAlly',
+    turn,
+    phase,
+    owner,
+    sequence,
+  ]);
+}
+export function emperorNexusSignature(record: object): string {
+  return JSON.stringify({ ...record, signature: undefined });
+}
+export function emperorNexusModeSupported(g: Game): boolean {
+  return (
+    !g.expansions.length &&
+    g.players.every((p) =>
+      ['atreides', 'harkonnen', 'fremen', 'guild', 'beneGesserit'].includes(
+        p.faction,
+      ),
+    ) &&
+    !g.homeworlds &&
+    !g.leaderSkills &&
+    !g.discoveryEnabled &&
+    !g.discoveries &&
+    !g.discoveryStash &&
+    !g.greatMaker &&
+    !g.techTokens &&
+    !g.strongholdCards
+  );
+}
+/** A fixed three-counter grant preserves the separate Advanced elite cap. */
+export function emperorNexusRevivalElites(
+  p: Player,
+  advanced: boolean,
+): number[] {
+  const choices: number[] = [];
+  for (let elite = 0; elite <= 3; elite++)
+    if (
+      elite <= eliteRevivalRemaining(p, advanced) &&
+      elite <= (p.elites?.tanks ?? 0) &&
+      3 - elite <= p.tanks - (p.elites?.tanks ?? 0)
+    )
+      choices.push(elite);
+  return choices;
+}
+export function validateEmperorNexusRevival(
+  g: Game,
+  r: NexusEmperorRevival,
+): void {
+  const p = r && g.players.find((p) => p.id === r.owner);
+  const validPools = (pool: EmperorNexusPools) =>
+    pool &&
+    Object.keys(pool).sort().join(',') ===
+      'eliteReserves,eliteRevived,eliteTanks,freeForcesRevived,reserves,revived,spice,tanks' &&
+    Object.entries(pool).every(
+      ([key, n]) =>
+        (key === 'freeForcesRevived' && n === null) ||
+        (Number.isSafeInteger(n) && n! >= 0),
+    ) &&
+    pool.eliteReserves <= pool.reserves &&
+    pool.eliteTanks <= pool.tanks &&
+    pool.reserves + pool.tanks <= 20;
+  if (
+    !p ||
+    Object.keys(r).sort().join(',') !==
+      'advanced,after,before,elite,event,faction,kind,owner,phase,sequence,signature,turn' ||
+    r.kind !== 'revival' ||
+    r.phase !== 4 ||
+    !Number.isSafeInteger(r.turn) ||
+    r.turn < 1 ||
+    r.turn > g.turn ||
+    r.faction !== p.faction ||
+    r.advanced !== g.advanced ||
+    !Number.isSafeInteger(r.sequence) ||
+    r.sequence < 0 ||
+    !Number.isSafeInteger(r.elite) ||
+    r.elite < 0 ||
+    r.elite > 3 ||
+    r.event !== emperorNexusEvent(r.turn, 4, r.owner, r.sequence) ||
+    r.signature !== emperorNexusSignature(r) ||
+    !validPools(r.before) ||
+    !validPools(r.after) ||
+    r.before.tanks < 3 ||
+    r.elite > r.before.eliteTanks ||
+    3 - r.elite > r.before.tanks - r.before.eliteTanks ||
+    (g.advanced && r.before.eliteRevived + r.elite > 1) ||
+    (p.faction !== 'fremen' &&
+      (r.elite || r.before.eliteTanks || r.before.eliteReserves)) ||
+    JSON.stringify(r.after) !==
+      JSON.stringify({
+        ...r.before,
+        reserves: r.before.reserves + 3,
+        tanks: r.before.tanks - 3,
+        eliteReserves: r.before.eliteReserves + r.elite,
+        eliteTanks: r.before.eliteTanks - r.elite,
+        eliteRevived: r.before.eliteRevived + r.elite,
+      })
+  )
+    throw new Error(
+      'Emperor Nexus revival has lost its exact original physical return or allowance.',
+    );
+}

game/reference.ts

@@ -3508,6 +3508,29 @@ export const RULE_TOPICS: RuleTopic[] = [
       { area: 'Verification', status: 'Partial', detail: 'Focused rules, private controls, AI, saved continuation and competing SQLite actions. Complete family acceptance remains open.', evidence: ['tests/nexus-choam-trade.test.ts', 'tests/nexus-choam-trade-recovery.test.ts'] },
     ],
   },
+  {
+    id: 'nexus-emperor-secret-ally',
+    title: 'Emperor Nexus Secret Ally: extra revivals',
+    category: 'Advanced & expansions',
+    coverage: 'Partial',
+    developmentStage: 'Prototyped',
+    summary: 'When Emperor is absent, an unallied holder can spend its Nexus card during Revival to return exactly three additional forces free. The purchase alternative and combined-module acceptance remain unfinished.',
+    steps: [
+      'Use the private Emperor Secret Ally controls during Revival. Select the physical elite count when more than one legal group is available. The card returns exactly three eligible forces from Tanks to reserves and is discarded once.',
+      'These returns cost no spice and do not consume ordinary force-revival or free-revival allowances. You may use the card before or after ordinary revivals, while Revival remains open.',
+      'The Advanced one-per-turn Fedaykin limit still applies across ordinary revivals and this card. The extra total allowance does not permit another elite revival. Fewer than three eligible counters is an unresolved case and remains unavailable.',
+      'This prototype supports Basic and Advanced base factions with Nexus alone. Other expansion, Homeworld, suppression and combined-module effects retain their separate boundaries. Keeping the card creates no public decision or extra confirmation.',
+      'The purchase alternative is not yet playable. It requires a choice when buying without revealing concealed card eligibility; its uniform winner-payment interaction awaits a product decision.',
+    ],
+    related: ['nexus-cards', 'revival'],
+    checklist: [
+      { area: 'Implementation', status: 'Partial', detail: 'Connected fixed three-force return with preserved ordinary allowances, physical elite limits and saved card-use receipts. Purchase and combined producers remain unfinished.', evidence: ['game/nexus-emperor-secret-ally.ts', 'game/engine.ts'] },
+      { area: 'Player controls', status: 'Partial', detail: 'Private optional revival controls, legal elite selection, unavailable reasons and readable card reference.', evidence: ['components/nexus-emperor-secret-ally.tsx', 'components/nexus-cards.tsx'] },
+      { area: 'AI', status: 'Partial', detail: 'All four profiles use the same projected legal return; no rival hand or spice is consulted. Complete Nexus strategy remains uncalibrated.', evidence: ['game/nexus-emperor-secret-ally-options.ts', 'game/bots.ts'] },
+      { area: 'Documentation', status: 'Partial', detail: 'Printed grant, separate allowances, elite cap and purchase timing boundary are explicit.', evidence: ['docs/NEXUS_EMPEROR_RULES.md', 'docs/NEXUS_EMPEROR_SECRET_ALLY_RUNTIME.md'] },
+      { area: 'Verification', status: 'Partial', detail: 'Focused rules, controls, bots, JSON and SQLite restoration with stale, duplicate and concurrent actions. Broader module acceptance remains open.', evidence: ['tests/nexus-emperor-secret-ally.test.ts', 'tests/nexus-emperor-secret-ally-controls.test.tsx', 'tests/nexus-emperor-secret-ally-bots.test.ts', 'tests/nexus-emperor-secret-ally-recovery.test.ts'] },
+    ],
+  },
   {
     id: 'nexus-cards',
     title: 'Nexus Cards',
@@ -3537,7 +3560,7 @@ export const RULE_TOPICS: RuleTopic[] = [
       'One Karama response covers the entire declared territory set. Cancellation keeps every selected group as advisors and leaves the Nexus card spent. Existing territory restrictions still apply; fresh accompanied advisors and storm-related conversion remain unavailable pending their rulings.',
       'Bene Gesserit Secret Ally borrowed Voice remains unavailable pending its cancellation and timing interpretation. Its printed permission does not make the other unfinished effects available.',
       'Emperor Cunning requires an Advanced battle with at least five ordinary Emperor counters and no actual Sardaukar, before submitting your plan. The played Nexus card opens one Karama response. Allowing it makes five ordinary counters count as Sardaukar for this battle; cancellation prevents the entire enhancement and leaves the Nexus card spent.',
-      'Temporary Sardaukar use the applicable strength and support rules, including the Fremen exception, but remain physically ordinary counters. Their losses go to Tanks as ordinary counters, without changing starred reserves or Tanks. Existing inspected or promised plans remain binding. The role ends after this battle; fewer-than-five groups and other Emperor Nexus modes remain unavailable.',
+      'Temporary Sardaukar use the applicable strength and support rules, including the Fremen exception, but remain physically ordinary counters. Their losses go to Tanks as ordinary counters, without changing starred reserves or Tanks. Existing inspected or promised plans remain binding. The role ends after this battle; fewer-than-five groups remain unavailable. The separate Secret Ally revival has its own connected controls; other Emperor modes remain unfinished.',
       'CHOAM Secret Ally has a working Collection trade: when CHOAM is absent, an unallied holder may discard one Worthless card and the Nexus card for two bank spice. Its after-victory inspection remains unfinished.',
       'CHOAM Cunning spends its Nexus card to use one held Treachery Card for one chosen Worthless effect at that effect’s normal timing, in Basic and Advanced. Choose the physical card separately from the effect. Kulon, La La La, Baliset, Jubba Cloak and Trip to Gamont are supported; Kull Wahad’s Karama-prevention reaction remains unavailable.',
       'One Karama response covers the CHOAM effect. Cancellation leaves the chosen Treachery Card in hand and the Nexus spent. An allowed use discards the actual card once, retaining its printed identity and applicable discard consequences; it does not create a named Worthless card or a turn-long conversion permission.',