Domaine : lire et écrire le lien d'une position (ADR 0013)

Le moteur écrit et décode le Match ID ; readPosition valide un lien,
linkOf donne celui d'une partie, setupOf la partie à jouer depuis la
position. Scénario « Partager une position », fiche « Lien de position ».

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

app/src/domain/game/engine.ts

@@ -74,6 +74,36 @@ export interface Engine {
 
     /** La chance d'un jet pour le joueur au trait. */
     luck(position: PositionId, cube: EngineCube, roll: Roll): Promise<Luck>;
+
+    /** Le Match ID d'une partie libre, joueur 0 au trait, avec ce videau vu
+     * de lui, sans dés. */
+    encodeMatch(cube: EngineCube): Promise<MatchId>;
+
+    /** Un Match ID décodé ; erreur s'il est illisible pour le moteur. */
+    decodeMatch(matchId: MatchId): Promise<MatchDescription>;
+}
+
+/**
+ * Identifiant de match (Match ID de gnubg, 12 caractères) : score, longueur
+ * du match, videau, joueur au trait. Le domaine ne le décode jamais
+ * lui-même : il le passe au moteur.
+ *
+ * Glossaire : docs/glossaire/identifiant-de-match.md
+ */
+export type MatchId = string;
+
+/** Un Match ID décodé par le moteur. Les joueurs sont numérotés 0 et 1,
+ * comme dans gnubg. Les dés qu'il peut contenir ne sont pas lus. */
+export interface MatchDescription {
+    /** 0 : partie libre. */
+    readonly matchLength: number;
+    readonly score: readonly [number, number];
+    readonly cubeValue: number;
+    /** -1 : videau au centre ; sinon le joueur qui le possède. */
+    readonly cubeOwner: -1 | 0 | 1;
+    readonly playerOnRoll: 0 | 1;
+    readonly crawford: boolean;
+    readonly jacoby: boolean;
 }
 
 /**

app/src/domain/game/position-link.ts

@@ -0,0 +1,126 @@
+// Une position du plateau dans un lien (ADR 0013) : le Position ID et le
+// Match ID de GNU Backgammon, lus et écrits par le moteur.
+//
+// Copyright (C) 2026 les auteurs d'Ustagammon.
+// Licence : GPLv3 ou ultérieure (voir LICENSE).
+//
+// Un lien décrit la position du point de vue du joueur au trait : c'est lui
+// qu'on montre en bas (« vous »), et c'est lui que l'on joue avec « Jouer à
+// partir d'ici ». Rien n'est décodé ici : le moteur valide et décode les deux
+// identifiants (aucune règle de représentation n'est réimplémentée).
+
+import type { Cube } from "./cube.js";
+import type { BoardResult, Engine, EngineCube, MatchId } from "./engine.js";
+import type { GameSetup, SideBoards } from "./game.js";
+import type { PositionId } from "./position.js";
+import type { Side } from "./side.js";
+import type { GameState } from "./state.js";
+
+/**
+ * Ce que porte l'adresse d'une position : son Position ID, et son Match ID
+ * s'il est donné (sans lui : partie libre, videau au centre).
+ *
+ * Glossaire : docs/glossaire/lien-de-position.md
+ */
+export interface PositionLink {
+    readonly position: PositionId;
+    readonly matchId: MatchId | null;
+}
+
+/** Une position partagée, lue par le moteur. Le camp « player » est celui
+ * au trait. */
+export interface SharedPosition {
+    readonly link: PositionLink;
+    readonly sides: SideBoards;
+    readonly cube: Cube;
+    /** null en partie libre ; sinon la longueur du match et le score. */
+    readonly match: {
+        readonly length: number;
+        readonly score: Readonly<Record<Side, number>>;
+    } | null;
+    /** La partie est déjà finie dans cette position (null sinon). */
+    readonly result: BoardResult | null;
+}
+
+/** Un lien que le moteur ne sait pas lire. */
+export class UnreadableLinkError extends Error {
+    constructor(reason: string) {
+        super(reason);
+        this.name = "UnreadableLinkError";
+    }
+}
+
+/**
+ * Lit une position partagée : le moteur décode le Match ID (s'il est
+ * donné), puis la position avec son videau. Erreur UnreadableLinkError si
+ * l'un des deux est illisible.
+ */
+export async function readPosition(engine: Engine, link: PositionLink): Promise<SharedPosition> {
+    let cube: EngineCube = { value: 1, owner: "centered" };
+    let match: SharedPosition["match"] = null;
+    if (link.matchId !== null) {
+        const description = await engine.decodeMatch(link.matchId).catch((error: unknown) => {
+            throw new UnreadableLinkError(`Match ID illisible : ${message(error)}`);
+        });
+        const onRoll = description.playerOnRoll;
+        cube = {
+            value: description.cubeValue,
+            owner:
+                description.cubeOwner === -1
+                    ? "centered"
+                    : description.cubeOwner === onRoll
+                      ? "onRoll"
+                      : "opponent",
+        };
+        if (description.matchLength > 0) {
+            match = {
+                length: description.matchLength,
+                score: {
+                    player: description.score[onRoll],
+                    computer: description.score[onRoll === 0 ? 1 : 0],
+                },
+            };
+        }
+    }
+    const board = await engine.board(link.position, cube).catch((error: unknown) => {
+        throw new UnreadableLinkError(`Position ID illisible : ${message(error)}`);
+    });
+    return {
+        link,
+        sides: { player: board.onRoll, computer: board.opponent },
+        cube: {
+            value: cube.value,
+            owner:
+                cube.owner === "centered" ? null : cube.owner === "onRoll" ? "player" : "computer",
+        },
+        match,
+        result: board.result,
+    };
+}
+
+/**
+ * Le lien de la position d'une partie : la position vue du camp au trait,
+ * et le Match ID que le moteur écrit pour son videau (partie libre, sans
+ * dés). Pendant le jet d'ouverture, la position de départ, vue du joueur.
+ */
+export async function linkOf(engine: Engine, state: GameState): Promise<PositionLink> {
+    const onRoll: Side = state.turn ?? "player";
+    const cube: EngineCube =
+        state.cube.owner === null
+            ? { value: state.cube.value, owner: "centered" }
+            : {
+                  value: state.cube.value,
+                  owner: state.cube.owner === onRoll ? "onRoll" : "opponent",
+              };
+    return { position: state.position, matchId: await engine.encodeMatch(cube) };
+}
+
+/** La partie à commencer avec « Jouer à partir d'ici » : le joueur prend la
+ * place du camp au trait, avec le même videau ; partie libre. */
+export function setupOf(shared: SharedPosition): GameSetup {
+    return { position: shared.link.position, firstTurn: "player", cube: shared.cube };
+}
+
+function message(error: unknown): string {
+    return error instanceof Error ? error.message : String(error);
+}