galaxy-game/ui/frontend/src/sync/order-draft.svelte.ts

// Per-game runes store that owns the local order draft. Mirrors the
// Phase 11 `GameStateStore` lifecycle: one instance per game, created
// in `routes/games/[id]/+layout.svelte`, exposed to descendants via
// Svelte context, disposed when the layout unmounts.
//
// Draft state is persisted into the platform `Cache` under the
// `order-drafts` namespace with a per-game key, so a reload, a
// browser restart, or a navigation through the lobby and back into
// the same game restores the previously composed list.
//
// Phase 14 wires the auto-sync pipeline: every successful mutation
// (`add` / `remove` / `move`) coalesces a `submitOrder` call so the
// server always mirrors the local draft. The Submit button is gone —
// the player's intent is the source of truth and the engine is kept
// in lock-step. Phase 26 will hide the order tab in history mode
// through a flag passed by the layout (the store itself remains
// alive across that transition so the draft survives history-mode
// round-trips).
//
// The store deliberately carries no Svelte component imports so it
// can be tested directly with a synthetic `Cache` without rendering
// any UI.

import type { Cache } from "../platform/store/index";
import type { GalaxyClient } from "../api/galaxy-client";
import { fetchOrder } from "./order-load";
import {
	isRelation,
	isShipGroupCargo,
	isShipGroupUpgradeTech,
	type CommandStatus,
	type OrderCommand,
} from "./order-types";
import { submitOrder } from "./submit";
import { validateEntityName } from "$lib/util/entity-name";
import { validateShipClass } from "$lib/util/ship-class-validation";
import { validateScience } from "$lib/util/science-validation";

const NAMESPACE = "order-drafts";
const draftKey = (gameId: string): string => `${gameId}/draft`;

/**
 * ORDER_DRAFT_CONTEXT_KEY is the Svelte context key the in-game shell
 * layout uses to expose its `OrderDraftStore` instance to descendants.
 * The order tab and any later command-builder UI resolve the store via
 * `getContext(ORDER_DRAFT_CONTEXT_KEY)`.
 */
export const ORDER_DRAFT_CONTEXT_KEY = Symbol("order-draft");

type Status = "idle" | "ready" | "error";

export type SyncStatus = "idle" | "syncing" | "synced" | "error";

export class OrderDraftStore {
	commands: OrderCommand[] = $state([]);
	statuses: Record<string, CommandStatus> = $state({});
	updatedAt = $state(0);
	status: Status = $state("idle");
	error: string | null = $state(null);

	/**
	 * syncStatus reflects the auto-sync pipeline state for the order
	 * tab status bar:
	 *   - `idle`    — no sync attempted yet (e.g. fresh draft after
	 *                 hydration or before the first mutation).
	 *   - `syncing` — a `submitOrder` call is in flight.
	 *   - `synced`  — the last sync succeeded; statuses match the
	 *                 server's view.
	 *   - `error`   — the last sync failed (network or non-`ok`); the
	 *                 next mutation triggers a retry, or the user can
	 *                 force a re-sync via `forceSync`.
	 */
	syncStatus: SyncStatus = $state("idle");
	syncError: string | null = $state(null);

	private cache: Cache | null = null;
	private gameId = "";
	private destroyed = false;
	private client: GalaxyClient | null = null;
	private syncing: Promise<void> | null = null;
	private pending = false;

	/**
	 * init loads the persisted draft for `opts.gameId` from `opts.cache`
	 * into `commands` and flips `status` to `ready`. The call is
	 * idempotent on the same store instance — the layout always
	 * constructs a fresh store per game, so there is no need to support
	 * mid-life game switching here.
	 *
	 * The cache load is the fast path so the order tab paints
	 * immediately on reopening the game; `hydrateFromServer` (called
	 * by the layout once the current turn is known) is the
	 * authoritative read that always overwrites the local cache when
	 * the server has a stored order.
	 */
	async init(opts: { cache: Cache; gameId: string }): Promise<void> {
		this.cache = opts.cache;
		this.gameId = opts.gameId;
		try {
			const stored = await opts.cache.get<OrderCommand[]>(
				NAMESPACE,
				draftKey(opts.gameId),
			);
			if (this.destroyed) return;
			this.commands = Array.isArray(stored) ? [...stored] : [];
			this.recomputeStatuses();
			this.status = "ready";
		} catch (err) {
			if (this.destroyed) return;
			this.status = "error";
			this.error = err instanceof Error ? err.message : "load failed";
		}
	}

	/**
	 * bindClient stores the per-game `GalaxyClient` so subsequent
	 * mutations can drive the auto-sync pipeline. The layout calls
	 * this after the boot `Promise.all` resolves and before
	 * `hydrateFromServer`, so any mutation that lands afterwards goes
	 * through the network.
	 */
	bindClient(client: GalaxyClient): void {
		this.client = client;
	}

	/**
	 * hydrateFromServer issues `user.games.order.get` for the current
	 * turn and overwrites the local cache with the server's stored
	 * order. The server is the source of truth: a player who logged
	 * in from a fresh device must see their existing orders, and a
	 * cache that's out-of-sync (e.g. a stale browser tab) is
	 * superseded by the gateway's view. A `found = false` answer
	 * empties the local draft. Network failures keep the local cache
	 * intact and surface as `syncStatus = "error"`.
	 */
	async hydrateFromServer(opts: {
		client: GalaxyClient;
		turn: number;
	}): Promise<void> {
		if (this.status !== "ready") return;
		this.client = opts.client;
		// Guard against placeholder game ids the Phase 10 e2e specs
		// still use — auto-sync needs a real UUID for the FBS request
		// envelope, and a parser exception here would only be visible
		// as a noisy `console.warn` deep in the layout boot path.
		if (!isUuid(this.gameId)) {
			this.syncStatus = "idle";
			return;
		}
		this.syncStatus = "syncing";
		this.syncError = null;
		try {
			const fetched = await fetchOrder(opts.client, this.gameId, opts.turn);
			if (this.destroyed) return;
			this.commands = fetched.commands;
			this.updatedAt = fetched.updatedAt;
			this.recomputeStatuses();
			// Server-fetched commands echo cmdApplied=true for entries
			// that survived previous turns; keep them as `applied` so
			// the overlay continues to project them on the inspector.
			const next = { ...this.statuses };
			for (const cmd of this.commands) {
				if (next[cmd.id] === "valid") {
					next[cmd.id] = "applied";
				}
			}
			this.statuses = next;
			await this.persist();
			this.syncStatus = "synced";
		} catch (err) {
			if (this.destroyed) return;
			this.syncStatus = "error";
			this.syncError = err instanceof Error ? err.message : "fetch failed";
			console.warn("order-draft: server hydration failed", err);
		}
	}

	/**
	 * add appends a command to the end of the draft, runs local
	 * validation for the new entry, persists the updated list, and
	 * triggers an auto-sync to keep the server in lock-step.
	 * Mutations made before `init` resolves are ignored — the layout
	 * always awaits `init` before exposing the store.
	 *
	 * Collapse rules:
	 *
	 *   - `setProductionType` collapses by `planetNumber`: a new
	 *     entry supersedes any prior `setProductionType` for the
	 *     same planet, so the draft holds at most one production
	 *     choice per planet.
	 *   - `setCargoRoute` and `removeCargoRoute` share a collapse
	 *     key on `(sourcePlanetNumber, loadType)` — the engine
	 *     stores a single (planet, type) → destination mapping, so
	 *     a newer entry for the same slot supersedes any prior
	 *     `set` or `remove` for that slot. Different load-types or
	 *     different sources coexist.
	 *   - `setDiplomaticStance` collapses by `acceptor`: the engine
	 *     tracks a single war/peace stance per opponent, so a newer
	 *     entry supersedes any prior `setDiplomaticStance` for the
	 *     same other race.
	 *   - `setVoteRecipient` collapses singleton: per `rules.txt`
	 *     each race controls a single vote slot, so a newer entry
	 *     supersedes any prior `setVoteRecipient` regardless of the
	 *     acceptor.
	 *   - `planetRename` and `placeholder` append unconditionally;
	 *     each rename is a distinct user-visible action.
	 */
	async add(command: OrderCommand): Promise<void> {
		if (this.status !== "ready") return;
		const removed: string[] = [];
		let nextCommands: OrderCommand[];
		if (command.kind === "setProductionType") {
			nextCommands = [];
			for (const existing of this.commands) {
				if (
					existing.kind === "setProductionType" &&
					existing.planetNumber === command.planetNumber
				) {
					removed.push(existing.id);
					continue;
				}
				nextCommands.push(existing);
			}
			nextCommands.push(command);
		} else if (
			command.kind === "setCargoRoute" ||
			command.kind === "removeCargoRoute"
		) {
			nextCommands = [];
			for (const existing of this.commands) {
				if (
					(existing.kind === "setCargoRoute" ||
						existing.kind === "removeCargoRoute") &&
					existing.sourcePlanetNumber === command.sourcePlanetNumber &&
					existing.loadType === command.loadType
				) {
					removed.push(existing.id);
					continue;
				}
				nextCommands.push(existing);
			}
			nextCommands.push(command);
		} else if (command.kind === "setDiplomaticStance") {
			nextCommands = [];
			for (const existing of this.commands) {
				if (
					existing.kind === "setDiplomaticStance" &&
					existing.acceptor === command.acceptor
				) {
					removed.push(existing.id);
					continue;
				}
				nextCommands.push(existing);
			}
			nextCommands.push(command);
		} else if (command.kind === "setVoteRecipient") {
			nextCommands = [];
			for (const existing of this.commands) {
				if (existing.kind === "setVoteRecipient") {
					removed.push(existing.id);
					continue;
				}
				nextCommands.push(existing);
			}
			nextCommands.push(command);
		} else {
			nextCommands = [...this.commands, command];
		}
		this.commands = nextCommands;
		const nextStatuses = { ...this.statuses };
		for (const id of removed) {
			delete nextStatuses[id];
		}
		nextStatuses[command.id] = validateCommand(command);
		this.statuses = nextStatuses;
		await this.persist();
		this.scheduleSync();
	}

	/**
	 * remove drops the command with the given id from the draft,
	 * persists the result, and triggers an auto-sync. A miss is a
	 * no-op. Even removing the last command sends an explicit empty
	 * order to the server so its stored state matches the local one
	 * (the engine accepts an empty `cmd[]` per the order handler).
	 */
	async remove(id: string): Promise<void> {
		if (this.status !== "ready") return;
		const next = this.commands.filter((cmd) => cmd.id !== id);
		if (next.length === this.commands.length) return;
		this.commands = next;
		const nextStatuses = { ...this.statuses };
		delete nextStatuses[id];
		this.statuses = nextStatuses;
		await this.persist();
		this.scheduleSync();
	}

	/**
	 * move relocates the command at `fromIndex` to `toIndex`, shifting
	 * the intermediate commands. Out-of-range indices and identical
	 * positions are no-ops; both indices are clamped against the
	 * current `commands` length. Triggers an auto-sync — the server
	 * stores commands in submission order and the engine relies on
	 * that order at turn cutoff.
	 */
	async move(fromIndex: number, toIndex: number): Promise<void> {
		if (this.status !== "ready") return;
		const length = this.commands.length;
		if (fromIndex < 0 || fromIndex >= length) return;
		if (toIndex < 0 || toIndex >= length) return;
		if (fromIndex === toIndex) return;
		const next = [...this.commands];
		const [picked] = next.splice(fromIndex, 1);
		if (picked === undefined) return;
		next.splice(toIndex, 0, picked);
		this.commands = next;
		await this.persist();
		this.scheduleSync();
	}

	/**
	 * forceSync re-runs the auto-sync without requiring a mutation.
	 * Used by the order tab's retry-on-error affordance.
	 */
	forceSync(): void {
		this.scheduleSync();
	}

	dispose(): void {
		this.destroyed = true;
		this.cache = null;
		this.client = null;
	}

	private scheduleSync(): void {
		if (this.client === null) return;
		// Same UUID guard as `hydrateFromServer` — placeholder game
		// ids in test fixtures must not blow up the auto-sync path.
		if (!isUuid(this.gameId)) return;
		if (this.syncing !== null) {
			this.pending = true;
			return;
		}
		this.syncing = this.runSync().finally(() => {
			this.syncing = null;
		});
	}

	private async runSync(): Promise<void> {
		while (true) {
			this.pending = false;
			const client = this.client;
			if (client === null || this.destroyed) return;

			// Capture the snapshot up-front: the in-flight request
			// reflects the draft as it was when the mutation landed,
			// even if the user adds another command before the
			// gateway responds.
			const snapshot: OrderCommand[] = $state.snapshot(
				this.commands,
			) as OrderCommand[];
			// Auto-sync sends every command the player still has in
			// the draft except the locally-invalid ones (we can't
			// expect the server to accept a name that fails our own
			// validator) and the Phase 12 placeholder. `applied` and
			// `rejected` entries are re-sent so the server's stored
			// view always mirrors the local one — re-applying an
			// already-applied command is idempotent at the engine
			// level (the rename ends at the same name).
			const submittable = snapshot.filter((cmd) => {
				const status = this.statuses[cmd.id];
				return status !== "invalid" && status !== "draft";
			});
			const submittingIds = submittable.map((cmd) => cmd.id);

			this.markSubmittingInternal(submittingIds);
			this.syncStatus = "syncing";
			this.syncError = null;

			try {
				const result = await submitOrder(
					client,
					this.gameId,
					submittable,
					{ updatedAt: this.updatedAt },
				);
				if (this.destroyed) return;
				if (result.ok) {
					this.applyResultsInternal(result.results, result.updatedAt);
					// Even with `result.ok === true` an individual
					// command may have been rejected by the engine
					// (e.g. validation passed transcoders but failed
					// the in-game rule). Surface that as an error in
					// the sync bar so the player notices and can fix
					// or remove the offending command.
					const anyRejected = Array.from(result.results.values()).some(
						(s) => s === "rejected",
					);
					this.syncStatus = anyRejected ? "error" : "synced";
					this.syncError = anyRejected
						? "engine rejected one or more commands"
						: null;
				} else {
					this.markRejectedInternal(submittingIds);
					this.syncStatus = "error";
					this.syncError = result.message;
				}
			} catch (err) {
				if (this.destroyed) return;
				this.revertSubmittingToValidInternal();
				this.syncStatus = "error";
				this.syncError = err instanceof Error ? err.message : "sync failed";
			}

			if (!this.pending) return;
		}
	}

	private markSubmittingInternal(ids: string[]): void {
		const next = { ...this.statuses };
		for (const id of ids) {
			// `applied` rows stay applied while the wire request is in
			// flight — re-sending an already-applied command is a
			// no-op idempotent operation, and flipping the badge back
			// to `submitting` would flicker the inspector overlay.
			if (next[id] === "valid" || next[id] === "rejected") {
				next[id] = "submitting";
			}
		}
		this.statuses = next;
	}

	private applyResultsInternal(
		results: Map<string, CommandStatus>,
		updatedAt: number,
	): void {
		const liveIds = new Set(this.commands.map((cmd) => cmd.id));
		const next = { ...this.statuses };
		for (const [id, status] of results.entries()) {
			// Drop verdicts for commands the user removed while the
			// request was in flight — they are no longer in the
			// draft, so re-introducing a stale `applied` row would
			// confuse the order tab and the overlay.
			if (!liveIds.has(id)) continue;
			next[id] = status;
		}
		this.statuses = next;
		this.updatedAt = updatedAt;
	}

	private markRejectedInternal(ids: string[]): void {
		const next = { ...this.statuses };
		for (const id of ids) {
			next[id] = "rejected";
		}
		this.statuses = next;
	}

	private revertSubmittingToValidInternal(): void {
		const next = { ...this.statuses };
		for (const cmd of this.commands) {
			if (next[cmd.id] === "submitting") {
				next[cmd.id] = validateCommand(cmd);
			}
		}
		this.statuses = next;
	}

	private recomputeStatuses(): void {
		const next: Record<string, CommandStatus> = {};
		for (const cmd of this.commands) {
			next[cmd.id] = validateCommand(cmd);
		}
		this.statuses = next;
	}

	private async persist(): Promise<void> {
		if (this.cache === null || this.destroyed) return;
		// `commands` is `$state`, so individual entries are proxies.
		// IndexedDB's structured clone refuses to clone proxies, so the
		// snapshot must be taken before the put.
		const snapshot = $state.snapshot(this.commands) as OrderCommand[];
		await this.cache.put(NAMESPACE, draftKey(this.gameId), snapshot);
	}
}

const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

function isUuid(value: string): boolean {
	return UUID_RE.test(value);
}

function validateCommand(cmd: OrderCommand): CommandStatus {
	switch (cmd.kind) {
		case "planetRename":
			return validateEntityName(cmd.name).ok ? "valid" : "invalid";
		case "setProductionType":
			// Mirrors the engine's `subject=Production` validator
			// (`game/internal/router/validator.go`): SCIENCE and SHIP
			// require a non-empty entity-name-valid subject; the other
			// six production types accept any subject (typically empty)
			// because the engine only consults the subject for those
			// two cases.
			if (
				cmd.productionType === "SCIENCE" ||
				cmd.productionType === "SHIP"
			) {
				return validateEntityName(cmd.subject).ok ? "valid" : "invalid";
			}
			return "valid";
		case "setCargoRoute":
			// The picker pre-checks reach (and so refuses to emit a
			// route to an unreachable destination) and the engine
			// re-validates ownership / reach server-side. Locally we
			// only refuse a self-route — the FBS validator
			// (`pkg/model/order/order.go`) accepts every other
			// (origin, destination, load_type) triple.
			if (cmd.sourcePlanetNumber === cmd.destinationPlanetNumber) {
				return "invalid";
			}
			return "valid";
		case "removeCargoRoute":
			// `removeCargoRoute` carries no destination; the only
			// engine-side check is ownership of the source planet,
			// which the inspector enforces by only mounting the
			// component on `kind === "local"`.
			return "valid";
		case "createShipClass":
			// Mirrors `pkg/calc/validator.go.ValidateShipTypeValues`
			// plus the entity-name rules. The duplicate-name check is
			// the designer's responsibility (it sees the live overlay
			// list); here the validator runs without `existingNames`
			// so a draft that was valid at creation time does not flip
			// to invalid just because another `createShipClass` for
			// the same name landed in the draft afterwards — both
			// rows ride out the wire and the engine arbitrates.
			return validateShipClass({
				name: cmd.name,
				drive: cmd.drive,
				armament: cmd.armament,
				weapons: cmd.weapons,
				shields: cmd.shields,
				cargo: cmd.cargo,
			}).ok
				? "valid"
				: "invalid";
		case "removeShipClass":
			// `removeShipClass` carries only the name; the engine
			// checks that the class exists and is not referenced by
			// active production / ship groups. Local validation only
			// guards the name shape.
			return validateEntityName(cmd.name).ok ? "valid" : "invalid";
		case "createScience":
			// Mirrors `pkg/calc/validator.go.ValidateScienceValues`
			// plus the entity-name rules. The wire shape is fractions
			// (sum to 1.0); the validator runs without `existingNames`
			// here for the same reason ship-class create does — a
			// duplicate-name check is the designer's UX responsibility,
			// not the draft store's.
			return validateScience({
				name: cmd.name,
				drive: cmd.drive * 100,
				weapons: cmd.weapons * 100,
				shields: cmd.shields * 100,
				cargo: cmd.cargo * 100,
			}).ok
				? "valid"
				: "invalid";
		case "removeScience":
			// `removeScience` carries only the name; the engine checks
			// that the science exists and is not referenced by active
			// production. Local validation only guards the name shape.
			return validateEntityName(cmd.name).ok ? "valid" : "invalid";
		case "breakShipGroup":
			// Engine rule (`controller/ship_group.go.breakGroup`):
			// quantity must be at least 1 and strictly less than the
			// source group size. We do not know the source size here
			// (it lives on the report), so the inspector enforces the
			// upper bound before emitting; locally we only refuse the
			// degenerate cases — non-positive `quantity`, missing or
			// equal UUIDs.
			if (cmd.quantity <= 0) return "invalid";
			if (!isUuid(cmd.groupId) || !isUuid(cmd.newGroupId)) return "invalid";
			if (cmd.groupId === cmd.newGroupId) return "invalid";
			return "valid";
		case "sendShipGroup":
			// Reach is enforced by the picker before the command lands
			// in the draft. Locally we only refuse a degenerate
			// destination (the engine uses planet number `0` as the
			// "no planet" sentinel; FBS encodes as `int64`, so any
			// strictly-positive number is wire-valid).
			if (cmd.destinationPlanetNumber <= 0) return "invalid";
			if (!isUuid(cmd.groupId)) return "invalid";
			return "valid";
		case "loadShipGroup":
			// Cargo type and quantity are pre-checked by the inspector
			// against the planet stock and the group's free capacity;
			// local validation only guards the wire-valid shape.
			if (!isShipGroupCargo(cmd.cargo)) return "invalid";
			if (cmd.quantity <= 0) return "invalid";
			if (!isUuid(cmd.groupId)) return "invalid";
			return "valid";
		case "unloadShipGroup":
			if (cmd.quantity <= 0) return "invalid";
			if (!isUuid(cmd.groupId)) return "invalid";
			return "valid";
		case "upgradeShipGroup":
			// Engine rule
			// (`controller/ship_group_upgrade.go.shipGroupUpgrade:56`):
			// `tech === "ALL"` requires `level === 0`; per-block tech
			// requires a strictly positive level. The inspector also
			// caps the level to the player's race tech, but the
			// engine re-validates server-side.
			if (!isShipGroupUpgradeTech(cmd.tech)) return "invalid";
			if (cmd.tech === "ALL") {
				if (cmd.level !== 0) return "invalid";
			} else if (cmd.level <= 0) {
				return "invalid";
			}
			if (!isUuid(cmd.groupId)) return "invalid";
			return "valid";
		case "dismantleShipGroup":
			return isUuid(cmd.groupId) ? "valid" : "invalid";
		case "transferShipGroup":
			// `acceptor` is a race name; race names follow the same
			// entity-name rules as planet/fleet names. The inspector
			// restricts the picker to `GameReport.otherRaces`, so a
			// locally-valid name is always a real race.
			if (!validateEntityName(cmd.acceptor).ok) return "invalid";
			if (!isUuid(cmd.groupId)) return "invalid";
			return "valid";
		case "joinFleetShipGroup":
			if (!validateEntityName(cmd.name).ok) return "invalid";
			if (!isUuid(cmd.groupId)) return "invalid";
			return "valid";
		case "setDiplomaticStance":
			// `acceptor` is the opponent's race name; race names follow
			// the same entity-name rules as planet/fleet names. The
			// races-table view restricts the per-row picker to live
			// `GameReport.races[]` entries, so a locally-valid name is
			// always a real race. `relation` must be one of the two
			// wire-stable values (`WAR` or `PEACE`); the FBS
			// `UNKNOWN = 0` sentinel is never emitted.
			if (!validateEntityName(cmd.acceptor).ok) return "invalid";
			if (!isRelation(cmd.relation)) return "invalid";
			return "valid";
		case "setVoteRecipient":
			// `acceptor` is the race the local player votes for. The
			// engine accepts a self-vote as the neutral default
			// (`controller/race.go`), so the table picker may include
			// the local race as a valid choice. Local validation only
			// guards the name shape.
			if (!validateEntityName(cmd.acceptor).ok) return "invalid";
			return "valid";
		case "placeholder":
			// Phase 12 placeholder entries are content-free and never
			// transition out of `draft` — they are not submittable.
			return "draft";
	}
}