@chaos-overlords/kernel 0.1.0

package/dist/services/RetentionService.js

@@ -0,0 +1,36 @@
+/** Matches that will never be played again, and are therefore the only ones retention may delete. */
+const COLLECTABLE = ['finished', 'abandoned', 'lobby'];
+export const DEFAULT_RETENTION = {
+    maxAgeMs: 30 * 24 * 60 * 60 * 1000,
+    batchSize: 50,
+};
+/**
+ * Deletes the matches nobody will come back to. A coordination server accumulates rows that have no
+ * second use — a finished match's order documents, a megabyte of snapshot per desync, the lobby
+ * someone opened and never started — and a self-hosted SQLite file has no operator watching it
+ * grow. Deleting the match row takes everything it owns with it, because every child table cascades.
+ *
+ * Running and desynced matches are never in scope at any age: a desync pause is not abandonment.
+ */
+export class RetentionService {
+    deps;
+    policy;
+    constructor(deps, policy = DEFAULT_RETENTION) {
+        this.deps = deps;
+        this.policy = policy;
+    }
+    async collect() {
+        if (this.policy.maxAgeMs <= 0)
+            return 0;
+        const before = new Date(this.deps.clock.now().getTime() - this.policy.maxAgeMs);
+        const deleted = await this.deps.storage.matches.deleteInactive(COLLECTABLE, before, this.policy.batchSize);
+        if (deleted > 0) {
+            this.deps.logger.info('retention deleted inactive matches', {
+                deleted,
+                before: before.toISOString(),
+            });
+        }
+        return deleted;
+    }
+}
+//# sourceMappingURL=RetentionService.js.map

package/dist/services/RetentionService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RetentionService.js","sourceRoot":"","sources":["../../src/services/RetentionService.ts"],"names":[],"mappings":"AAGA,qGAAqG;AACrG,MAAM,WAAW,GAA2B,CAAC,UAAU,EAAE,WAAW,EAAE,OAAO,CAAC,CAAA;AAS9E,MAAM,CAAC,MAAM,iBAAiB,GAAoB;IAChD,QAAQ,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI;IAClC,SAAS,EAAE,EAAE;CACd,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,gBAAgB;IAER;IACA;IAFnB,YACmB,IAAsD,EACtD,SAA0B,iBAAiB;QAD3C,SAAI,GAAJ,IAAI,CAAkD;QACtD,WAAM,GAAN,MAAM,CAAqC;IAC3D,CAAC;IAEJ,KAAK,CAAC,OAAO;QACX,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,CAAC;YAAE,OAAO,CAAC,CAAA;QACvC,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;QAC/E,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,cAAc,CAC5D,WAAW,EACX,MAAM,EACN,IAAI,CAAC,MAAM,CAAC,SAAS,CACtB,CAAA;QACD,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;YAChB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,oCAAoC,EAAE;gBAC1D,OAAO;gBACP,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE;aAC7B,CAAC,CAAA;QACJ,CAAC;QACD,OAAO,OAAO,CAAA;IAChB,CAAC;CACF"}

package/dist/services/SnapshotService.d.ts

@@ -0,0 +1,40 @@
+import type { SnapshotView, UploadSnapshotRequest } from '@chaos-overlords/contracts';
+import type { Principal } from './AuthService';
+import type { KernelDeps } from './deps';
+import type { EventPublisher } from './EventPublisher';
+import type { TurnService } from './TurnService';
+/**
+ * Host-uploaded native snapshots: the recovery path for a desync and the bootstrap for a
+ * reconnecting client. The server stores bytes it never decodes; the hash beside them is what
+ * a desynced turn's reports are then judged against.
+ */
+export declare class SnapshotService {
+    private readonly deps;
+    private readonly publisher;
+    private readonly turns;
+    constructor(deps: KernelDeps, publisher: EventPublisher, turns: TurnService);
+    upload(principal: Principal, request: UploadSnapshotRequest): Promise<void>;
+    /**
+     * A recovery snapshot may only claim a state hash that the players themselves already computed
+     * in the greatest number.
+     *
+     * This is what keeps the host from arbitrating a disagreement it is a party to. The snapshot for
+     * a desynced turn becomes the hash every other client is told to converge on, so a host free to
+     * name any hash could resolve a deliberate desync in favour of a doctored state. A hash that more
+     * active players reported than any other cannot be minted by one of them. A tie leaves nothing to
+     * count and the host breaks it; turns with no reports at all (a bootstrap snapshot for a
+     * reconnecting client) are unconstrained, because there is no consensus to contradict yet.
+     */
+    private requireCorroboration;
+    /**
+     * Bound what one live match holds. A snapshot is a megabyte of base64 and a long match can desync
+     * many times; retention only collects matches that are over, so without this a single match that
+     * runs for months is unbounded growth. Only the recent ones have a use — a desync is repaired
+     * from the turn it happened on, and a reconnecting client bootstraps from the newest — so the
+     * older ones are dead weight. Failing to prune must never fail the upload that just succeeded.
+     */
+    private pruneOldSnapshots;
+    latest(matchId: string): Promise<SnapshotView>;
+    get(matchId: string, turn: number): Promise<SnapshotView>;
+}
+//# sourceMappingURL=SnapshotService.d.ts.map

package/dist/services/SnapshotService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SnapshotService.d.ts","sourceRoot":"","sources":["../../src/services/SnapshotService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA;AAIrF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAA;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAQhD;;;;GAIG;AACH,qBAAa,eAAe;IAExB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAFL,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,cAAc,EACzB,KAAK,EAAE,WAAW;IAG/B,MAAM,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAuDjF;;;;;;;;;;OAUG;YACW,oBAAoB;IAiBlC;;;;;;OAMG;YACW,iBAAiB;IASzB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAM9C,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;CAKhE"}

package/dist/services/SnapshotService.js

@@ -0,0 +1,137 @@
+import { ConflictError, ForbiddenError, NotFoundError } from '../domain/errors';
+import { authoritativeCandidates } from '../logic/turn-logic';
+/**
+ * Snapshots kept per live match. Enough to cover a desync being repaired while an earlier one is
+ * still being fetched by a straggler, and far fewer than a long match would otherwise accumulate.
+ */
+const SNAPSHOTS_KEPT_PER_MATCH = 5;
+/**
+ * Host-uploaded native snapshots: the recovery path for a desync and the bootstrap for a
+ * reconnecting client. The server stores bytes it never decodes; the hash beside them is what
+ * a desynced turn's reports are then judged against.
+ */
+export class SnapshotService {
+    deps;
+    publisher;
+    turns;
+    constructor(deps, publisher, turns) {
+        this.deps = deps;
+        this.publisher = publisher;
+        this.turns = turns;
+    }
+    async upload(principal, request) {
+        const { match, player } = principal;
+        if (player.id !== match.hostPlayerId) {
+            throw new ForbiddenError('Only the host uploads snapshots', { reason: 'host_only' });
+        }
+        if (match.status !== 'running' && match.status !== 'desynced') {
+            throw new ConflictError('The match is not in progress', { reason: 'match_not_running' });
+        }
+        if (request.turn > match.currentTurn) {
+            throw new ConflictError('Cannot snapshot a turn that has not opened', {
+                reason: 'future_turn',
+            });
+        }
+        if (request.turn === match.currentTurn && match.currentTurn > 0) {
+            throw new ConflictError('The current turn is still open; snapshot the last sealed turn', {
+                reason: 'turn_open',
+            });
+        }
+        // A confirmed turn's state hash is settled consensus. Re-uploading the same bytes is fine (a
+        // reconnecting client may need them); contradicting it is not, or the snapshot clients bootstrap
+        // from would disagree with the turn they already agreed on.
+        const turn = await this.deps.storage.turns.get(match.id, request.turn);
+        if (turn?.status === 'confirmed') {
+            const existing = await this.deps.storage.snapshots.get(match.id, request.turn);
+            if (existing && existing.stateHash !== request.stateHash) {
+                throw new ConflictError('Turn already confirmed with a different state hash', {
+                    reason: 'turn_confirmed',
+                    stateHash: existing.stateHash,
+                });
+            }
+        }
+        await this.requireCorroboration(match.id, request.turn, request.stateHash);
+        const snapshot = {
+            matchId: match.id,
+            turn: request.turn,
+            formatVersion: request.formatVersion,
+            stateHash: request.stateHash,
+            uploadedByPlayerId: player.id,
+            uploadedAt: this.deps.clock.now(),
+            body: request.body,
+        };
+        await this.deps.storage.snapshots.put(snapshot);
+        await this.pruneOldSnapshots(match.id);
+        await this.publisher.publish(match.id, {
+            type: 'snapshot.available',
+            payload: {
+                turn: request.turn,
+                formatVersion: request.formatVersion,
+                stateHash: request.stateHash,
+                uploadedByPlayerId: player.id,
+            },
+        });
+        await this.turns.settle(match.id, request.turn);
+    }
+    /**
+     * A recovery snapshot may only claim a state hash that the players themselves already computed
+     * in the greatest number.
+     *
+     * This is what keeps the host from arbitrating a disagreement it is a party to. The snapshot for
+     * a desynced turn becomes the hash every other client is told to converge on, so a host free to
+     * name any hash could resolve a deliberate desync in favour of a doctored state. A hash that more
+     * active players reported than any other cannot be minted by one of them. A tie leaves nothing to
+     * count and the host breaks it; turns with no reports at all (a bootstrap snapshot for a
+     * reconnecting client) are unconstrained, because there is no consensus to contradict yet.
+     */
+    async requireCorroboration(matchId, turn, stateHash) {
+        const [players, reports] = await Promise.all([
+            this.deps.storage.players.listByMatch(matchId),
+            this.deps.storage.turns.listReports(matchId, turn),
+        ]);
+        const candidates = authoritativeCandidates(players, reports);
+        if (candidates.length === 0 || candidates.includes(stateHash))
+            return;
+        throw new ConflictError('A recovery snapshot must match a state hash the players reported most often', { reason: 'uncorroborated_state_hash', candidateStateHashes: candidates });
+    }
+    /**
+     * Bound what one live match holds. A snapshot is a megabyte of base64 and a long match can desync
+     * many times; retention only collects matches that are over, so without this a single match that
+     * runs for months is unbounded growth. Only the recent ones have a use — a desync is repaired
+     * from the turn it happened on, and a reconnecting client bootstraps from the newest — so the
+     * older ones are dead weight. Failing to prune must never fail the upload that just succeeded.
+     */
+    async pruneOldSnapshots(matchId) {
+        try {
+            const dropped = await this.deps.storage.snapshots.prune(matchId, SNAPSHOTS_KEPT_PER_MATCH);
+            if (dropped > 0)
+                this.deps.logger.debug('pruned old snapshots', { matchId, dropped });
+        }
+        catch (error) {
+            this.deps.logger.warn('could not prune old snapshots', { matchId, error: String(error) });
+        }
+    }
+    async latest(matchId) {
+        const snapshot = await this.deps.storage.snapshots.getLatest(matchId);
+        if (!snapshot)
+            throw new NotFoundError('No snapshot uploaded yet', { reason: 'no_snapshot' });
+        return toView(snapshot);
+    }
+    async get(matchId, turn) {
+        const snapshot = await this.deps.storage.snapshots.get(matchId, turn);
+        if (!snapshot)
+            throw new NotFoundError('No snapshot for that turn', { reason: 'no_snapshot' });
+        return toView(snapshot);
+    }
+}
+function toView(snapshot) {
+    return {
+        turn: snapshot.turn,
+        formatVersion: snapshot.formatVersion,
+        stateHash: snapshot.stateHash,
+        uploadedByPlayerId: snapshot.uploadedByPlayerId,
+        uploadedAt: snapshot.uploadedAt.toISOString(),
+        body: snapshot.body,
+    };
+}
+//# sourceMappingURL=SnapshotService.js.map

package/dist/services/SnapshotService.js.map

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

package/dist/services/TurnService.d.ts

@@ -0,0 +1,63 @@
+import { type OwnSubmissionView, type SubmitOrdersRequest, type TurnReportRequest } from '@chaos-overlords/contracts';
+import { type Match } from '../domain/entities';
+import type { Principal } from './AuthService';
+import type { KernelDeps } from './deps';
+import type { EventPublisher } from './EventPublisher';
+export type SealTrigger = 'ready' | 'deadline';
+/** Turns are numbered from 1; 0 is the lobby's `currentTurn`, before any turn exists. */
+export declare const FIRST_TURN = 1;
+/**
+ * The simultaneous-turn barrier. Players submit orders privately; the turn seals when every
+ * active player is ready or the deadline passes; the sealed set becomes readable and the next
+ * turn opens at once. Clients resolve the turn locally and report the resulting state hash, and
+ * the server confirms the turn on agreement or flags a desync.
+ *
+ * Every state change here is a compare-and-swap, so concurrent callers (the last player's ready
+ * racing the timer, two players' reports landing together) produce exactly one seal and one
+ * verdict. Sealing is a CAS followed by `completeSeal`, which is idempotent from any point: that is
+ * what lets `sweep` finish a seal whose process died halfway through instead of stranding the match.
+ */
+export declare class TurnService {
+    private readonly deps;
+    private readonly publisher;
+    constructor(deps: KernelDeps, publisher: EventPublisher);
+    submitOrders(principal: Principal, number: number, request: SubmitOrdersRequest): Promise<OwnSubmissionView>;
+    /** Seal `number` if its trigger condition holds. Returns whether THIS call sealed it. */
+    trySeal(matchId: string, number: number, trigger: SealTrigger): Promise<boolean>;
+    /**
+     * Everything that follows the seal's compare-and-swap: freeze the participant set and its digest,
+     * announce it, and open the next turn. Each step is conditional on its own predecessor, so a call
+     * on a turn that is already complete changes nothing and a call on one that stopped halfway
+     * finishes it. Orders are immutable from the CAS onwards, so the digest it derives is stable.
+     */
+    private completeSeal;
+    /**
+     * Opens turn `number` for every active player and arms its deadline. Idempotent: the insert is
+     * refused if the turn already exists, and only the caller that created it announces it. Returns
+     * whether this call created the turn.
+     */
+    openTurn(match: Match, number: number): Promise<boolean>;
+    /**
+     * The safety net behind the scheduler and behind any interrupted seal: seal every open turn whose
+     * deadline has passed, then finish every seal that stopped before opening its successor. Runtimes
+     * call this on an interval (Node) or a cron (Cloudflare).
+     */
+    sweep(limit?: number): Promise<{
+        sealed: number;
+        repaired: number;
+    }>;
+    report(principal: Principal, number: number, request: TurnReportRequest): Promise<void>;
+    /** Authenticated turn activity wins the race with an AI vote and restores the human seat. */
+    private restorePendingPlayer;
+    /** Re-run the verdict of every unconfirmed turn and the auto-seal of the open one. */
+    reevaluate(matchId: string): Promise<void>;
+    /** Decide turn `number` from the reports on file. Idempotent and race-safe through CAS. */
+    settle(matchId: string, number: number): Promise<void>;
+    /**
+     * Lift a desync pause once nothing is unsettled. Orders were refused for the whole pause while
+     * the open turn's deadline kept running, so the turn would otherwise seal empty the moment the
+     * match resumes: its clock restarts here, and clients are told the new deadline.
+     */
+    private resumeAfterDesync;
+}
+//# sourceMappingURL=TurnService.d.ts.map

package/dist/services/TurnService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TurnService.d.ts","sourceRoot":"","sources":["../../src/services/TurnService.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACvB,MAAM,4BAA4B,CAAA;AACnC,OAAO,EAAoC,KAAK,KAAK,EAAmB,MAAM,oBAAoB,CAAA;AAIlG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAA;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAEtD,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,UAAU,CAAA;AAE9C,yFAAyF;AACzF,eAAO,MAAM,UAAU,IAAI,CAAA;AAE3B;;;;;;;;;;GAUG;AACH,qBAAa,WAAW;IAEpB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBADT,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,cAAc;IAGtC,YAAY,CAChB,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,iBAAiB,CAAC;IAmC7B,yFAAyF;IACnF,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IA0BtF;;;;;OAKG;YACW,YAAY;IAyD1B;;;;OAIG;IACG,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAmC9D;;;;OAIG;IACG,KAAK,CAAC,KAAK,SAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAqBjE,MAAM,CAAC,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAyB7F,6FAA6F;YAC/E,oBAAoB;IASlC,sFAAsF;IAChF,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAShD,2FAA2F;IACrF,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2E5D;;;;OAIG;YACW,iBAAiB;CA6BhC"}