@game-infra/game-state-schemas 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Savin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# @game-infra/game-state-schemas
+
+API contract for **play state**: valibot schemas plus [toad-contracts](https://github.com/kibertoad/toad-contracts) `defineApiContract` definitions for the sessions a player has in progress, the journal each one is rebuilt from, and the payload shapes freeform mode puts inside them. Builds on `@game-infra/api-schemas-core` for the shared success-response wrapper.
+
+Published to npm. Also consumable as sibling source (`exports` points at `src/`).
+
+## The line this package draws
+
+`@game-infra/story-schemas` carries what an **author** writes: one world, read by every player, the same tomorrow as today. This package carries what a **player** produces: one run, belonging to them alone, rewritten every turn, and gone when they abandon it.
+
+|              | design content (`story-schemas`) | play state (this package) |
+| ------------ | -------------------------------- | ------------------------- |
+| Written by   | an author, once                  | a player, every turn      |
+| Read by      | every player of the game         | one player                |
+| Lifetime     | as long as the game              | as long as the run        |
+| Deleted with | the world                        | the session               |
+| Service      | `game-content-service`           | `game-state-service`      |
+
+Keeping both in one resource meant one listing, one delete sweep and one retention policy for two things that share none of those — and it meant a design database growing without bound with other people's abandoned runs.
+
+## Install
+
+```jsonc
+// pnpm sibling checkout
+"@game-infra/game-state-schemas": "link:../../game-infra/packages/schemas/game-state-schemas"
+// or from npm
+"@game-infra/game-state-schemas": "^0.1.0"
+```
+
+`valibot` is a peer dependency (`^1.4.0`); the consumer provides it. `@game-infra/api-schemas-core` and `@game-infra/event-schemas` are runtime dependencies — the first for the success-response wrapper, the second for the `ActivationDTO` effect vocabulary a freeform turn shares with an authored story branch.
+
+## Two shapes, seven endpoints
+
+A **session** is the header of one playthrough: the world or campaign it plays (`scopeId`), what to call it in a picker, and an opaque payload for whatever else the game needs to resume. A **journal entry** is one recorded step of that session, numbered from zero, so folding the entries in order rebuilds the session's whole state.
+
+| Contract                      | Method + path                               | What it is for                                |
+| ----------------------------- | ------------------------------------------- | --------------------------------------------- |
+| `gameSessionListContract`     | `GET /games/:gameId/sessions`               | the caller's runs, most recently played first |
+| `gameSessionLoadContract`     | `GET /games/:gameId/sessions/:sessionId`    | one session header                            |
+| `gameSessionSaveContract`     | `PUT /games/:gameId/sessions/:sessionId`    | begin a run, or rename one                    |
+| `gameSessionDeleteContract`   | `DELETE /games/:gameId/sessions/:sessionId` | drop a run and its whole journal              |
+| `gameJournalListContract`     | `GET …/:sessionId/journal`                  | the entries to fold, in `sequence` order      |
+| `gameJournalAppendContract`   | `PUT …/:sessionId/journal/:sequence`        | record one step                               |
+| `gameJournalTruncateContract` | `DELETE …/:sessionId/journal/:sequence`     | correct a step, or undo back to one           |
+
+Every route is scoped to the authenticated caller: a session id is unique per player, not per game, so two players may both call their first run `slot-1` and neither can read the other's.
+
+`sequence` is the ordering, and it is an integer — there is no sort key to mint and no zero-padded id to keep sortable as text. `SequenceParamSchema` validates the path segment in the contract, so no handler re-checks it.
+
+## Usage
+
+```ts
+import { gameJournalAppendContract, gameSessionListContract } from "@game-infra/game-state-schemas";
+import { mapApiContractToPath } from "@toad-contracts/valibot";
+
+gameSessionListContract.pathResolver({ gameId: "g1" }); // '/games/g1/sessions'
+mapApiContractToPath(gameJournalAppendContract);
+// '/games/:gameId/sessions/:sessionId/journal/:sequence'
+```
+
+Register on a Hono service with `@toad-contracts/hono` (`buildHonoRoute`) and call from a frontend with `@toad-contracts/frontend-http-client` (`sendByApiContract`) — both drive off the same contract objects.
+
+Undo is a truncation, not a delete:
+
+```ts
+// drop turn 12 and everything after it — a journal is folded in order, so
+// keeping the tail would replay effects whose cause is gone
+await sendByApiContract(http, gameJournalTruncateContract, {
+  pathParams: { gameId: "g1", sessionId: "s1", sequence: "12" },
+  queryParams: { truncate: "following" },
+});
+```
+
+## Freeform mode — a journal, not a tree
+
+Story mode stores a tree of pregenerated beats addressed by the choices taken to reach them. Freeform play follows the player's own words, so it stores a linear journal instead: one session, one entry per turn. Replaying the journal rebuilds the whole run — play state, cast and memory — so nothing else is stored.
+
+`FreeformTurnPayloadSchema` is what goes inside an entry's `data`: the player's input, the narration, the neurons the adjudicator judged relevant (`focus`), the check it rolled (`ResolvedCheckDTOSchema` — rolled once, recorded forever, never re-rolled on replay), effects in the same `ActivationDTO` vocabulary a story branch carries, the characters the turn introduced (`IntroducedEntityDTOSchema`, id and name guaranteed and the game's own definition passed through), the memories it formed and the consolidations it performed. `FreeformSessionPayloadSchema` is the session header's payload.
+
+Memory is a synapse graph. Each `MemoryDTO` connects to **neurons** — `character:tallow`, `faction:ash-wardens`, or a domain such as `domain:war` (see `FREEFORM_DOMAINS`, and `neuronKey`/`parseNeuronKey` for the spelling) — and recall walks those connections rather than the whole journal. Over time small memories consolidate: a `ConsolidationDTO` names the entries a single summary supersedes, so five small grievances become "many past grievances" on replay exactly as they did in play.
+
+None of these payload schemas is attached to an endpoint — the service stores `data` opaquely — but two clients reading the same session must agree on the shapes.
+
+## Savegames
+
+Slot snapshots are `game-state-service`'s other half, but their contracts predate this package and stay where they are, in `@game-infra/api-schemas-core`: `savegameSaveContract`, `savegameLoadContract`, `savegameListSlotsContract`, at `/users/:userId/games/:gameId/saves/:saveSlot`. A published shape does not move just to sit next to its neighbours.
+
+A save is a snapshot a player can return to; a session is the run they are in the middle of. A game may use either, or both — freeform mode uses only the journal, because the journal _is_ the save.
+
+## Extension points
+
+- **`data`**: opaque to the contract on both shapes, so a game evolves its play vocabulary without a contract bump.
+- **`scopeId`**: the world, campaign or scenario a session plays. A game with a single unnamed setting uses `ROOT_SESSION_SCOPE`.
+- **Domain neurons**: `FREEFORM_DOMAINS` is a suggested set, not a closed one — a domain neuron is just a key.
+- **Effect vocabulary**: `type` is free text in `ActivationDTOSchema`, so each game declares the set it evaluates and drops the rest.
+
+## Dependencies
+
+`@game-infra/api-schemas-core` (the success-response wrapper), `@game-infra/event-schemas` (the `ActivationDTO` effect vocabulary), `@toad-contracts/core`, `@toad-contracts/valibot`; peer `valibot`.
+
+## Consumers
+
+`services/game-state-service` (the Hono service registering these routes) and the play clients that call them — currently the Fluid Emerald game client.

package/dist/contracts.d.ts

@@ -0,0 +1,220 @@
+/**
+ * The caller's sessions for this game, most recently played first.
+ *
+ * This is the "continue playing" listing: which runs exist, what to call them,
+ * how long each one is, and when it was last touched.
+ */
+export declare const gameSessionListContract: {
+    readonly method: "get";
+    readonly requestPathParamsSchema: import("valibot").ObjectSchema<{
+        readonly gameId: import("valibot").StringSchema<undefined>;
+    }, undefined> & import("@toad-contracts/valibot").StandardObjectKeysV1<unknown, unknown>;
+    readonly requestQuerySchema: import("valibot").ObjectSchema<{
+        readonly scopeId: import("valibot").OptionalSchema<import("valibot").StringSchema<undefined>, undefined>;
+        readonly includeData: import("valibot").OptionalSchema<import("valibot").StringSchema<undefined>, undefined>;
+    }, undefined>;
+    readonly pathResolver: ({ gameId }: {
+        gameId: string;
+    }) => string;
+    readonly responsesByStatusCode: {
+        200: import("valibot").ObjectSchema<{
+            readonly success: import("valibot").BooleanSchema<undefined>;
+            readonly error: import("valibot").OptionalSchema<import("valibot").StringSchema<undefined>, undefined>;
+        } & {
+            items: import("valibot").OptionalSchema<import("valibot").ArraySchema<import("valibot").ObjectSchema<{
+                readonly sessionId: import("valibot").StringSchema<undefined>;
+                readonly scopeId: import("valibot").StringSchema<undefined>;
+                readonly name: import("valibot").StringSchema<undefined>;
+                readonly data: import("valibot").OptionalSchema<import("valibot").StringSchema<undefined>, undefined>;
+                readonly entryCount: import("valibot").OptionalSchema<import("valibot").NumberSchema<undefined>, undefined>;
+                readonly createdAt: import("valibot").StringSchema<undefined>;
+                readonly updatedAt: import("valibot").StringSchema<undefined>;
+            }, undefined>, undefined>, undefined>;
+        }, undefined>;
+    };
+};
+/** One session header, or `item: undefined` when the caller has no such session. */
+export declare const gameSessionLoadContract: {
+    readonly method: "get";
+    readonly requestPathParamsSchema: import("valibot").ObjectSchema<{
+        readonly gameId: import("valibot").StringSchema<undefined>;
+        readonly sessionId: import("valibot").StringSchema<undefined>;
+    }, undefined> & import("@toad-contracts/valibot").StandardObjectKeysV1<unknown, unknown>;
+    readonly pathResolver: ({ gameId, sessionId }: {
+        gameId: string;
+        sessionId: string;
+    }) => string;
+    readonly responsesByStatusCode: {
+        200: import("valibot").ObjectSchema<{
+            readonly success: import("valibot").BooleanSchema<undefined>;
+            readonly error: import("valibot").OptionalSchema<import("valibot").StringSchema<undefined>, undefined>;
+        } & {
+            item: import("valibot").OptionalSchema<import("valibot").ObjectSchema<{
+                readonly sessionId: import("valibot").StringSchema<undefined>;
+                readonly scopeId: import("valibot").StringSchema<undefined>;
+                readonly name: import("valibot").StringSchema<undefined>;
+                readonly data: import("valibot").OptionalSchema<import("valibot").StringSchema<undefined>, undefined>;
+                readonly entryCount: import("valibot").OptionalSchema<import("valibot").NumberSchema<undefined>, undefined>;
+                readonly createdAt: import("valibot").StringSchema<undefined>;
+                readonly updatedAt: import("valibot").StringSchema<undefined>;
+            }, undefined>, undefined>;
+        }, undefined>;
+    };
+};
+/**
+ * Create or replace a session header.
+ *
+ * The journal is untouched, so this is both "begin a run" and "rename one".
+ * It is a `put` because the client names the session: an id it minted is the
+ * same session whether or not the request that created it was retried.
+ */
+export declare const gameSessionSaveContract: {
+    readonly method: "put";
+    readonly requestPathParamsSchema: import("valibot").ObjectSchema<{
+        readonly gameId: import("valibot").StringSchema<undefined>;
+        readonly sessionId: import("valibot").StringSchema<undefined>;
+    }, undefined> & import("@toad-contracts/valibot").StandardObjectKeysV1<unknown, unknown>;
+    readonly pathResolver: ({ gameId, sessionId }: {
+        gameId: string;
+        sessionId: string;
+    }) => string;
+    readonly requestBodySchema: import("valibot").ObjectSchema<{
+        readonly scopeId: import("valibot").StringSchema<undefined>;
+        readonly name: import("valibot").StringSchema<undefined>;
+        readonly data: import("valibot").StringSchema<undefined>;
+    }, undefined>;
+    readonly responsesByStatusCode: {
+        200: import("valibot").ObjectSchema<{
+            readonly success: import("valibot").BooleanSchema<undefined>;
+            readonly error: import("valibot").OptionalSchema<import("valibot").StringSchema<undefined>, undefined>;
+        } & {
+            sessionId: import("valibot").OptionalSchema<import("valibot").StringSchema<undefined>, undefined>;
+        }, undefined>;
+    };
+};
+/**
+ * Delete a session and its whole journal.
+ *
+ * There is no cascade option because there is no other shape it could take: a
+ * journal without its session is unreadable, and a session without its journal
+ * is a run that cannot be resumed.
+ */
+export declare const gameSessionDeleteContract: {
+    readonly method: "delete";
+    readonly requestPathParamsSchema: import("valibot").ObjectSchema<{
+        readonly gameId: import("valibot").StringSchema<undefined>;
+        readonly sessionId: import("valibot").StringSchema<undefined>;
+    }, undefined> & import("@toad-contracts/valibot").StandardObjectKeysV1<unknown, unknown>;
+    readonly pathResolver: ({ gameId, sessionId }: {
+        gameId: string;
+        sessionId: string;
+    }) => string;
+    readonly responsesByStatusCode: {
+        200: import("valibot").ObjectSchema<{
+            readonly success: import("valibot").BooleanSchema<undefined>;
+            readonly error: import("valibot").OptionalSchema<import("valibot").StringSchema<undefined>, undefined>;
+        } & {
+            deletedCount: import("valibot").OptionalSchema<import("valibot").NumberSchema<undefined>, undefined>;
+        }, undefined>;
+    };
+};
+/**
+ * A session's journal in `sequence` order — the entries a client folds to
+ * rebuild the run.
+ *
+ * `fromSequence` returns the entries at or after that position, which is how a
+ * client that already holds the first hundred turns asks only for the rest.
+ */
+export declare const gameJournalListContract: {
+    readonly method: "get";
+    readonly requestPathParamsSchema: import("valibot").ObjectSchema<{
+        readonly gameId: import("valibot").StringSchema<undefined>;
+        readonly sessionId: import("valibot").StringSchema<undefined>;
+    }, undefined> & import("@toad-contracts/valibot").StandardObjectKeysV1<unknown, unknown>;
+    readonly requestQuerySchema: import("valibot").ObjectSchema<{
+        readonly fromSequence: import("valibot").OptionalSchema<import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").RegexAction<string, "sequence must be a non-negative integer">]>, undefined>;
+        readonly includeData: import("valibot").OptionalSchema<import("valibot").StringSchema<undefined>, undefined>;
+    }, undefined>;
+    readonly pathResolver: ({ gameId, sessionId }: {
+        gameId: string;
+        sessionId: string;
+    }) => string;
+    readonly responsesByStatusCode: {
+        200: import("valibot").ObjectSchema<{
+            readonly success: import("valibot").BooleanSchema<undefined>;
+            readonly error: import("valibot").OptionalSchema<import("valibot").StringSchema<undefined>, undefined>;
+        } & {
+            entries: import("valibot").OptionalSchema<import("valibot").ArraySchema<import("valibot").ObjectSchema<{
+                readonly sequence: import("valibot").NumberSchema<undefined>;
+                readonly name: import("valibot").StringSchema<undefined>;
+                readonly data: import("valibot").OptionalSchema<import("valibot").StringSchema<undefined>, undefined>;
+                readonly createdAt: import("valibot").StringSchema<undefined>;
+                readonly updatedAt: import("valibot").StringSchema<undefined>;
+            }, undefined>, undefined>, undefined>;
+        }, undefined>;
+    };
+};
+/**
+ * Write one journal entry at `sequence`.
+ *
+ * Writing a position that already exists replaces it, so re-recording a turn is
+ * the same call as recording it. The session's `updatedAt` moves with it, which
+ * is what keeps the "continue playing" listing in the order a player expects.
+ */
+export declare const gameJournalAppendContract: {
+    readonly method: "put";
+    readonly requestPathParamsSchema: import("valibot").ObjectSchema<{
+        readonly gameId: import("valibot").StringSchema<undefined>;
+        readonly sessionId: import("valibot").StringSchema<undefined>;
+        readonly sequence: import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").RegexAction<string, "sequence must be a non-negative integer">]>;
+    }, undefined> & import("@toad-contracts/valibot").StandardObjectKeysV1<unknown, unknown>;
+    readonly pathResolver: ({ gameId, sessionId, sequence }: {
+        gameId: string;
+        sessionId: string;
+        sequence: string;
+    }) => string;
+    readonly requestBodySchema: import("valibot").ObjectSchema<{
+        readonly name: import("valibot").StringSchema<undefined>;
+        readonly data: import("valibot").StringSchema<undefined>;
+    }, undefined>;
+    readonly responsesByStatusCode: {
+        200: import("valibot").ObjectSchema<{
+            readonly success: import("valibot").BooleanSchema<undefined>;
+            readonly error: import("valibot").OptionalSchema<import("valibot").StringSchema<undefined>, undefined>;
+        } & {
+            sequence: import("valibot").OptionalSchema<import("valibot").NumberSchema<undefined>, undefined>;
+        }, undefined>;
+    };
+};
+/**
+ * Drop a journal entry, and — with `?truncate=following` — everything after it.
+ *
+ * `following` is undo. A journal is folded in order, so dropping a step in the
+ * middle and keeping the tail would replay effects whose cause is gone; the
+ * default `entry` is for correcting the last step in place.
+ */
+export declare const gameJournalTruncateContract: {
+    readonly method: "delete";
+    readonly requestPathParamsSchema: import("valibot").ObjectSchema<{
+        readonly gameId: import("valibot").StringSchema<undefined>;
+        readonly sessionId: import("valibot").StringSchema<undefined>;
+        readonly sequence: import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").RegexAction<string, "sequence must be a non-negative integer">]>;
+    }, undefined> & import("@toad-contracts/valibot").StandardObjectKeysV1<unknown, unknown>;
+    readonly requestQuerySchema: import("valibot").ObjectSchema<{
+        readonly truncate: import("valibot").OptionalSchema<import("valibot").PicklistSchema<readonly ["entry", "following"], undefined>, undefined>;
+    }, undefined>;
+    readonly pathResolver: ({ gameId, sessionId, sequence }: {
+        gameId: string;
+        sessionId: string;
+        sequence: string;
+    }) => string;
+    readonly responsesByStatusCode: {
+        200: import("valibot").ObjectSchema<{
+            readonly success: import("valibot").BooleanSchema<undefined>;
+            readonly error: import("valibot").OptionalSchema<import("valibot").StringSchema<undefined>, undefined>;
+        } & {
+            deletedCount: import("valibot").OptionalSchema<import("valibot").NumberSchema<undefined>, undefined>;
+        }, undefined>;
+    };
+};
+//# sourceMappingURL=contracts.d.ts.map

package/dist/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AA6EA;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;QAKT,GAAG;;;;;;;;;;;;;;;CAC5B,CAAC;AAEH,oFAAoF;AACpF,eAAO,MAAM,uBAAuB;;;;;;;;;;;QAIT,GAAG;;;;;;;;;;;;;;;CAC5B,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;QAKT,GAAG;;;;;;;CAC5B,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;QAIX,GAAG;;;;;;;CAC5B,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;QAKT,GAAG;;;;;;;;;;;;;CAC5B,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;QAMX,GAAG;;;;;;;CAC5B,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;QAMb,GAAG;;;;;;;CAC5B,CAAC"}

package/dist/contracts.js

@@ -0,0 +1,147 @@
+import { defineApiContract, withObjectKeys } from "@toad-contracts/valibot";
+import { object, optional, string } from "valibot";
+import { GameJournalAppendRequestSchema, GameJournalAppendResponseSchema, GameJournalListResponseSchema, GameJournalTruncateResponseSchema, GameSessionDeleteResponseSchema, GameSessionListResponseSchema, GameSessionLoadResponseSchema, GameSessionSaveRequestSchema, GameSessionSaveResponseSchema, JournalTruncationSchema, SequenceParamSchema, } from "./sessionState.js";
+/**
+ * Typed endpoint contracts for play state: the sessions a player has in
+ * progress, and the journal each one is rebuilt from.
+ *
+ * They live behind `/games/:gameId/sessions`, and `game-state-service`
+ * implements them. Savegames — slot snapshots of a finished or paused run —
+ * are the same service's other half, but their contracts predate this package
+ * and stay in `@game-infra/api-schemas-core` (`savegameSaveContract` and
+ * friends) so that already-published shape does not move.
+ *
+ * Every route is scoped to the authenticated caller. A session id is unique per
+ * player, not per game: two players may both call their first run `slot-1`
+ * without colliding, and neither can read the other's.
+ *
+ * Register them on a Hono service with `@toad-contracts/hono` (`buildHonoRoute`)
+ * and call them from a client with `@toad-contracts/frontend-http-client`
+ * (`sendByApiContract`) — both drive off these same objects.
+ *
+ * @example
+ * ```ts
+ * import { gameSessionListContract, gameJournalAppendContract } from '@game-infra/game-state-schemas'
+ * import { mapApiContractToPath } from '@toad-contracts/valibot'
+ *
+ * gameSessionListContract.pathResolver({ gameId: 'g1' }) // '/games/g1/sessions'
+ * gameJournalAppendContract.pathResolver({ gameId: 'g1', sessionId: 's1', sequence: '7' })
+ * // '/games/g1/sessions/s1/journal/7'
+ * mapApiContractToPath(gameJournalAppendContract)
+ * // '/games/:gameId/sessions/:sessionId/journal/:sequence'
+ * ```
+ */
+const gameParams = withObjectKeys(object({ gameId: string() }));
+const sessionParams = withObjectKeys(object({ gameId: string(), sessionId: string() }));
+const entryParams = withObjectKeys(object({ gameId: string(), sessionId: string(), sequence: SequenceParamSchema }));
+/**
+ * `scopeId` narrows to the sessions playing one world or campaign;
+ * `includeData=true` opts into the headers' payloads, which a picker does not
+ * need and a resume does.
+ */
+const sessionListQuery = object({
+    scopeId: optional(string()),
+    includeData: optional(string()),
+});
+/**
+ * `fromSequence` resumes a journal a client already holds part of, and
+ * `includeData=false` asks for the shape of the journal without its payloads —
+ * the inverse default from a session listing, because a journal is normally
+ * read to be replayed.
+ */
+const journalListQuery = object({
+    fromSequence: optional(SequenceParamSchema),
+    includeData: optional(string()),
+});
+/** `truncate` is `entry` (default) or `following`. */
+const journalDeleteQuery = object({ truncate: optional(JournalTruncationSchema) });
+/**
+ * The caller's sessions for this game, most recently played first.
+ *
+ * This is the "continue playing" listing: which runs exist, what to call them,
+ * how long each one is, and when it was last touched.
+ */
+export const gameSessionListContract = defineApiContract({
+    method: "get",
+    requestPathParamsSchema: gameParams,
+    requestQuerySchema: sessionListQuery,
+    pathResolver: ({ gameId }) => `/games/${gameId}/sessions`,
+    responsesByStatusCode: { 200: GameSessionListResponseSchema },
+});
+/** One session header, or `item: undefined` when the caller has no such session. */
+export const gameSessionLoadContract = defineApiContract({
+    method: "get",
+    requestPathParamsSchema: sessionParams,
+    pathResolver: ({ gameId, sessionId }) => `/games/${gameId}/sessions/${sessionId}`,
+    responsesByStatusCode: { 200: GameSessionLoadResponseSchema },
+});
+/**
+ * Create or replace a session header.
+ *
+ * The journal is untouched, so this is both "begin a run" and "rename one".
+ * It is a `put` because the client names the session: an id it minted is the
+ * same session whether or not the request that created it was retried.
+ */
+export const gameSessionSaveContract = defineApiContract({
+    method: "put",
+    requestPathParamsSchema: sessionParams,
+    pathResolver: ({ gameId, sessionId }) => `/games/${gameId}/sessions/${sessionId}`,
+    requestBodySchema: GameSessionSaveRequestSchema,
+    responsesByStatusCode: { 200: GameSessionSaveResponseSchema },
+});
+/**
+ * Delete a session and its whole journal.
+ *
+ * There is no cascade option because there is no other shape it could take: a
+ * journal without its session is unreadable, and a session without its journal
+ * is a run that cannot be resumed.
+ */
+export const gameSessionDeleteContract = defineApiContract({
+    method: "delete",
+    requestPathParamsSchema: sessionParams,
+    pathResolver: ({ gameId, sessionId }) => `/games/${gameId}/sessions/${sessionId}`,
+    responsesByStatusCode: { 200: GameSessionDeleteResponseSchema },
+});
+/**
+ * A session's journal in `sequence` order — the entries a client folds to
+ * rebuild the run.
+ *
+ * `fromSequence` returns the entries at or after that position, which is how a
+ * client that already holds the first hundred turns asks only for the rest.
+ */
+export const gameJournalListContract = defineApiContract({
+    method: "get",
+    requestPathParamsSchema: sessionParams,
+    requestQuerySchema: journalListQuery,
+    pathResolver: ({ gameId, sessionId }) => `/games/${gameId}/sessions/${sessionId}/journal`,
+    responsesByStatusCode: { 200: GameJournalListResponseSchema },
+});
+/**
+ * Write one journal entry at `sequence`.
+ *
+ * Writing a position that already exists replaces it, so re-recording a turn is
+ * the same call as recording it. The session's `updatedAt` moves with it, which
+ * is what keeps the "continue playing" listing in the order a player expects.
+ */
+export const gameJournalAppendContract = defineApiContract({
+    method: "put",
+    requestPathParamsSchema: entryParams,
+    pathResolver: ({ gameId, sessionId, sequence }) => `/games/${gameId}/sessions/${sessionId}/journal/${sequence}`,
+    requestBodySchema: GameJournalAppendRequestSchema,
+    responsesByStatusCode: { 200: GameJournalAppendResponseSchema },
+});
+/**
+ * Drop a journal entry, and — with `?truncate=following` — everything after it.
+ *
+ * `following` is undo. A journal is folded in order, so dropping a step in the
+ * middle and keeping the tail would replay effects whose cause is gone; the
+ * default `entry` is for correcting the last step in place.
+ */
+export const gameJournalTruncateContract = defineApiContract({
+    method: "delete",
+    requestPathParamsSchema: entryParams,
+    requestQuerySchema: journalDeleteQuery,
+    pathResolver: ({ gameId, sessionId, sequence }) => `/games/${gameId}/sessions/${sessionId}/journal/${sequence}`,
+    responsesByStatusCode: { 200: GameJournalTruncateResponseSchema },
+});
+//# sourceMappingURL=contracts.js.map

package/dist/contracts.js.map

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