@game-infra/game-state-schemas 0.1.0

package/dist/sessionState.d.ts

@@ -0,0 +1,252 @@
+import { type InferOutput } from "valibot";
+/**
+ * The transport for everything that changes because someone is *playing*: the
+ * sessions a player has in progress, and the journal each one is rebuilt from.
+ *
+ * This is the counterpart to `@game-infra/story-schemas`, and the split is the
+ * point. Design content is authored — one copy, shared by every player, the
+ * same tomorrow as today. Session state is transient and personal — one copy
+ * per player per playthrough, rewritten every turn, and meaningless to anyone
+ * else. Storing them in one resource meant one delete sweep, one listing and
+ * one retention policy for two things that share none of those.
+ *
+ * Two shapes carry all of it:
+ *
+ * - a **session** — the header of one playthrough: which world or campaign it
+ *   plays, what to call it in a picker, and an opaque payload for whatever else
+ *   the game needs to resume;
+ * - a **journal entry** — one recorded step of that session, numbered, so
+ *   folding the entries in order rebuilds the session's whole state.
+ *
+ * As in design content, `data` is stored, indexed and returned but never parsed
+ * by the service, so a game's play vocabulary can move without a contract bump.
+ * The shapes that go *inside* it are typed too — see `freeformPayloads.ts` —
+ * but as schemas a client parses with, not as part of any endpoint.
+ */
+/**
+ * The scope of a session that plays nothing in particular. A session is
+ * normally scoped to the world or campaign it plays, but a game with a single
+ * unnamed setting has nothing to name, and a URL cannot carry an empty path
+ * segment, so unscoped sessions spell their scope `-`.
+ *
+ * @example
+ * ```ts
+ * import { ROOT_SESSION_SCOPE } from '@game-infra/game-state-schemas'
+ *
+ * const header = { scopeId: ROOT_SESSION_SCOPE, name: 'Slot 1', data: '{}' }
+ * ```
+ */
+export declare const ROOT_SESSION_SCOPE = "-";
+/**
+ * One playthrough in progress, as the service holds it.
+ *
+ * A session belongs to the caller who created it: every read and write is
+ * filtered by user id, so two players in the same game never see each other's
+ * sessions.
+ *
+ * `data` is present only when the request asked for it — a session picker needs
+ * titles and timestamps, not the premise of every abandoned run.
+ *
+ * @example
+ * ```ts
+ * import type { GameSessionRecord } from '@game-infra/game-state-schemas'
+ *
+ * const session: GameSessionRecord = {
+ *   sessionId: 'ash-and-embers',
+ *   scopeId: 'the-ash-reckoning',
+ *   name: 'Ash and Embers',
+ *   data: JSON.stringify({ title: 'Ash and Embers', premise: 'A drift-runner…' }),
+ *   entryCount: 12,
+ *   createdAt: '2026-08-29T09:00:00.000Z',
+ *   updatedAt: '2026-08-29T11:42:00.000Z',
+ * }
+ * ```
+ */
+export declare const GameSessionRecordSchema: import("valibot").ObjectSchema<{
+    readonly sessionId: import("valibot").StringSchema<undefined>;
+    /** The world, campaign or scenario being played, or {@link ROOT_SESSION_SCOPE}. */
+    readonly scopeId: import("valibot").StringSchema<undefined>;
+    /** For display in a session picker, so a listing need not carry payloads. */
+    readonly name: import("valibot").StringSchema<undefined>;
+    readonly data: import("valibot").OptionalSchema<import("valibot").StringSchema<undefined>, undefined>;
+    /** How many journal entries the session holds — its length, for a picker. */
+    readonly entryCount: import("valibot").OptionalSchema<import("valibot").NumberSchema<undefined>, undefined>;
+    readonly createdAt: import("valibot").StringSchema<undefined>;
+    readonly updatedAt: import("valibot").StringSchema<undefined>;
+}, undefined>;
+export type GameSessionRecord = InferOutput<typeof GameSessionRecordSchema>;
+/**
+ * Create or replace a session header. Re-saving the same id keeps its
+ * `createdAt` and leaves the journal alone, so renaming a session is one call.
+ *
+ * @example
+ * ```ts
+ * import type { GameSessionSaveRequest } from '@game-infra/game-state-schemas'
+ *
+ * const request: GameSessionSaveRequest = {
+ *   scopeId: 'the-ash-reckoning',
+ *   name: 'Ash and Embers',
+ *   data: JSON.stringify({ title: 'Ash and Embers', premise: 'A drift-runner…' }),
+ * }
+ * ```
+ */
+export declare const GameSessionSaveRequestSchema: import("valibot").ObjectSchema<{
+    readonly scopeId: import("valibot").StringSchema<undefined>;
+    readonly name: import("valibot").StringSchema<undefined>;
+    readonly data: import("valibot").StringSchema<undefined>;
+}, undefined>;
+export type GameSessionSaveRequest = InferOutput<typeof GameSessionSaveRequestSchema>;
+/**
+ * One recorded step of a session.
+ *
+ * `sequence` is the entry's position in the journal, counted from zero, and it
+ * is the whole ordering: entries come back in numeric order with no sort key to
+ * mint and no zero-padded id to keep sortable as text.
+ *
+ * @example
+ * ```ts
+ * import type { GameJournalEntryRecord } from '@game-infra/game-state-schemas'
+ *
+ * const entry: GameJournalEntryRecord = {
+ *   sequence: 7,
+ *   name: 'The tunnel breathes out ash',
+ *   data: JSON.stringify({ input: 'I follow the draught', narration: '…' }),
+ *   createdAt: '2026-08-29T11:40:00.000Z',
+ *   updatedAt: '2026-08-29T11:40:00.000Z',
+ * }
+ * ```
+ */
+export declare const GameJournalEntryRecordSchema: import("valibot").ObjectSchema<{
+    readonly sequence: import("valibot").NumberSchema<undefined>;
+    /** For display in a history list — a turn title, a chapter heading. */
+    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>;
+export type GameJournalEntryRecord = InferOutput<typeof GameJournalEntryRecordSchema>;
+/**
+ * Write one journal entry. Writing an existing `sequence` replaces it, which is
+ * how a turn is re-rolled or corrected without disturbing the ones after it.
+ *
+ * @example
+ * ```ts
+ * import type { GameJournalAppendRequest } from '@game-infra/game-state-schemas'
+ *
+ * const request: GameJournalAppendRequest = {
+ *   name: 'The tunnel breathes out ash',
+ *   data: JSON.stringify({ input: 'I follow the draught', narration: '…' }),
+ * }
+ * ```
+ */
+export declare const GameJournalAppendRequestSchema: import("valibot").ObjectSchema<{
+    readonly name: import("valibot").StringSchema<undefined>;
+    readonly data: import("valibot").StringSchema<undefined>;
+}, undefined>;
+export type GameJournalAppendRequest = InferOutput<typeof GameJournalAppendRequestSchema>;
+/**
+ * How far a journal delete reaches.
+ *
+ * - `entry` — that entry alone, for correcting one step in place.
+ * - `following` — that entry and every entry after it. This is undo: a journal
+ *   is folded in order, so keeping the tail after dropping a step in the middle
+ *   would replay effects that no longer have a cause.
+ */
+export declare const JOURNAL_TRUNCATIONS: readonly ["entry", "following"];
+export declare const JournalTruncationSchema: import("valibot").PicklistSchema<readonly ["entry", "following"], undefined>;
+export type JournalTruncation = InferOutput<typeof JournalTruncationSchema>;
+/**
+ * A journal position as it arrives in a path or query segment: digits, and
+ * short enough that no journal will ever reach it.
+ *
+ * Path segments are strings on the wire, so the shape is checked here — in the
+ * schema the contract references — rather than re-checked in every handler that
+ * reads one. Handlers take the number with `Number(...)`.
+ */
+export declare const SequenceParamSchema: import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").RegexAction<string, "sequence must be a non-negative integer">]>;
+/** The caller's sessions for this game, most recently played first. */
+export declare const GameSessionListResponseSchema: 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>;
+        /** The world, campaign or scenario being played, or {@link ROOT_SESSION_SCOPE}. */
+        readonly scopeId: import("valibot").StringSchema<undefined>;
+        /** For display in a session picker, so a listing need not carry payloads. */
+        readonly name: import("valibot").StringSchema<undefined>;
+        readonly data: import("valibot").OptionalSchema<import("valibot").StringSchema<undefined>, undefined>;
+        /** How many journal entries the session holds — its length, for a picker. */
+        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>;
+export type GameSessionListResponse = InferOutput<typeof GameSessionListResponseSchema>;
+/** One session header, absent when the caller has no session under that id. */
+export declare const GameSessionLoadResponseSchema: 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>;
+        /** The world, campaign or scenario being played, or {@link ROOT_SESSION_SCOPE}. */
+        readonly scopeId: import("valibot").StringSchema<undefined>;
+        /** For display in a session picker, so a listing need not carry payloads. */
+        readonly name: import("valibot").StringSchema<undefined>;
+        readonly data: import("valibot").OptionalSchema<import("valibot").StringSchema<undefined>, undefined>;
+        /** How many journal entries the session holds — its length, for a picker. */
+        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>;
+export type GameSessionLoadResponse = InferOutput<typeof GameSessionLoadResponseSchema>;
+/** The saved session's id, echoed back. */
+export declare const GameSessionSaveResponseSchema: 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>;
+export type GameSessionSaveResponse = InferOutput<typeof GameSessionSaveResponseSchema>;
+/** How many rows the delete removed — the session plus its journal entries. */
+export declare const GameSessionDeleteResponseSchema: 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>;
+export type GameSessionDeleteResponse = InferOutput<typeof GameSessionDeleteResponseSchema>;
+/** A session's journal, in `sequence` order. */
+export declare const GameJournalListResponseSchema: 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>;
+        /** For display in a history list — a turn title, a chapter heading. */
+        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>;
+export type GameJournalListResponse = InferOutput<typeof GameJournalListResponseSchema>;
+/** The written entry's position, echoed back. */
+export declare const GameJournalAppendResponseSchema: 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>;
+export type GameJournalAppendResponse = InferOutput<typeof GameJournalAppendResponseSchema>;
+/** How many entries the truncation removed — 0 when nothing matched. */
+export declare const GameJournalTruncateResponseSchema: 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>;
+export type GameJournalTruncateResponse = InferOutput<typeof GameJournalTruncateResponseSchema>;
+//# sourceMappingURL=sessionState.d.ts.map

package/dist/sessionState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionState.d.ts","sourceRoot":"","sources":["../src/sessionState.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,WAAW,EASjB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,uBAAuB;;IAElC,mFAAmF;;IAEnF,6EAA6E;;;IAG7E,6EAA6E;;;;aAI7E,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,WAAW,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE5E;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,4BAA4B;;;;aAIvC,CAAC;AAEH,MAAM,MAAM,sBAAsB,GAAG,WAAW,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAEtF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,4BAA4B;;IAEvC,uEAAuE;;;;;aAKvE,CAAC;AAEH,MAAM,MAAM,sBAAsB,GAAG,WAAW,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAEtF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,8BAA8B;;;aAGzC,CAAC;AAEH,MAAM,MAAM,wBAAwB,GAAG,WAAW,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAE1F;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,YAAI,OAAO,EAAE,WAAW,CAAU,CAAC;AAEnE,eAAO,MAAM,uBAAuB,8EAAgC,CAAC;AAErE,MAAM,MAAM,iBAAiB,GAAG,WAAW,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE5E;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,0KAG/B,CAAC;AAEF,uEAAuE;AACvE,eAAO,MAAM,6BAA6B;;;;;;QApHxC,mFAAmF;;QAEnF,6EAA6E;;;QAG7E,6EAA6E;;;;;aAiH7E,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,WAAW,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAExF,+EAA+E;AAC/E,eAAO,MAAM,6BAA6B;;;;;;QA3HxC,mFAAmF;;QAEnF,6EAA6E;;;QAG7E,6EAA6E;;;;;aAwH7E,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,WAAW,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAExF,2CAA2C;AAC3C,eAAO,MAAM,6BAA6B;;;;;aAExC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,WAAW,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAExF,+EAA+E;AAC/E,eAAO,MAAM,+BAA+B;;;;;aAE1C,CAAC;AAEH,MAAM,MAAM,yBAAyB,GAAG,WAAW,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAE5F,gDAAgD;AAChD,eAAO,MAAM,6BAA6B;;;;;;QAtFxC,uEAAuE;;;;;;aAwFvE,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,WAAW,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAExF,iDAAiD;AACjD,eAAO,MAAM,+BAA+B;;;;;aAE1C,CAAC;AAEH,MAAM,MAAM,yBAAyB,GAAG,WAAW,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAE5F,wEAAwE;AACxE,eAAO,MAAM,iCAAiC;;;;;aAE5C,CAAC;AAEH,MAAM,MAAM,2BAA2B,GAAG,WAAW,CAAC,OAAO,iCAAiC,CAAC,CAAC"}

package/dist/sessionState.js

@@ -0,0 +1,191 @@
+import { createSuccessResponseSchema } from "@game-infra/api-schemas-core";
+import { array, number, object, optional, picklist, pipe, regex, string, } from "valibot";
+/**
+ * The transport for everything that changes because someone is *playing*: the
+ * sessions a player has in progress, and the journal each one is rebuilt from.
+ *
+ * This is the counterpart to `@game-infra/story-schemas`, and the split is the
+ * point. Design content is authored — one copy, shared by every player, the
+ * same tomorrow as today. Session state is transient and personal — one copy
+ * per player per playthrough, rewritten every turn, and meaningless to anyone
+ * else. Storing them in one resource meant one delete sweep, one listing and
+ * one retention policy for two things that share none of those.
+ *
+ * Two shapes carry all of it:
+ *
+ * - a **session** — the header of one playthrough: which world or campaign it
+ *   plays, what to call it in a picker, and an opaque payload for whatever else
+ *   the game needs to resume;
+ * - a **journal entry** — one recorded step of that session, numbered, so
+ *   folding the entries in order rebuilds the session's whole state.
+ *
+ * As in design content, `data` is stored, indexed and returned but never parsed
+ * by the service, so a game's play vocabulary can move without a contract bump.
+ * The shapes that go *inside* it are typed too — see `freeformPayloads.ts` —
+ * but as schemas a client parses with, not as part of any endpoint.
+ */
+/**
+ * The scope of a session that plays nothing in particular. A session is
+ * normally scoped to the world or campaign it plays, but a game with a single
+ * unnamed setting has nothing to name, and a URL cannot carry an empty path
+ * segment, so unscoped sessions spell their scope `-`.
+ *
+ * @example
+ * ```ts
+ * import { ROOT_SESSION_SCOPE } from '@game-infra/game-state-schemas'
+ *
+ * const header = { scopeId: ROOT_SESSION_SCOPE, name: 'Slot 1', data: '{}' }
+ * ```
+ */
+export const ROOT_SESSION_SCOPE = "-";
+/**
+ * One playthrough in progress, as the service holds it.
+ *
+ * A session belongs to the caller who created it: every read and write is
+ * filtered by user id, so two players in the same game never see each other's
+ * sessions.
+ *
+ * `data` is present only when the request asked for it — a session picker needs
+ * titles and timestamps, not the premise of every abandoned run.
+ *
+ * @example
+ * ```ts
+ * import type { GameSessionRecord } from '@game-infra/game-state-schemas'
+ *
+ * const session: GameSessionRecord = {
+ *   sessionId: 'ash-and-embers',
+ *   scopeId: 'the-ash-reckoning',
+ *   name: 'Ash and Embers',
+ *   data: JSON.stringify({ title: 'Ash and Embers', premise: 'A drift-runner…' }),
+ *   entryCount: 12,
+ *   createdAt: '2026-08-29T09:00:00.000Z',
+ *   updatedAt: '2026-08-29T11:42:00.000Z',
+ * }
+ * ```
+ */
+export const GameSessionRecordSchema = object({
+    sessionId: string(),
+    /** The world, campaign or scenario being played, or {@link ROOT_SESSION_SCOPE}. */
+    scopeId: string(),
+    /** For display in a session picker, so a listing need not carry payloads. */
+    name: string(),
+    data: optional(string()),
+    /** How many journal entries the session holds — its length, for a picker. */
+    entryCount: optional(number()),
+    createdAt: string(),
+    updatedAt: string(),
+});
+/**
+ * Create or replace a session header. Re-saving the same id keeps its
+ * `createdAt` and leaves the journal alone, so renaming a session is one call.
+ *
+ * @example
+ * ```ts
+ * import type { GameSessionSaveRequest } from '@game-infra/game-state-schemas'
+ *
+ * const request: GameSessionSaveRequest = {
+ *   scopeId: 'the-ash-reckoning',
+ *   name: 'Ash and Embers',
+ *   data: JSON.stringify({ title: 'Ash and Embers', premise: 'A drift-runner…' }),
+ * }
+ * ```
+ */
+export const GameSessionSaveRequestSchema = object({
+    scopeId: string(),
+    name: string(),
+    data: string(),
+});
+/**
+ * One recorded step of a session.
+ *
+ * `sequence` is the entry's position in the journal, counted from zero, and it
+ * is the whole ordering: entries come back in numeric order with no sort key to
+ * mint and no zero-padded id to keep sortable as text.
+ *
+ * @example
+ * ```ts
+ * import type { GameJournalEntryRecord } from '@game-infra/game-state-schemas'
+ *
+ * const entry: GameJournalEntryRecord = {
+ *   sequence: 7,
+ *   name: 'The tunnel breathes out ash',
+ *   data: JSON.stringify({ input: 'I follow the draught', narration: '…' }),
+ *   createdAt: '2026-08-29T11:40:00.000Z',
+ *   updatedAt: '2026-08-29T11:40:00.000Z',
+ * }
+ * ```
+ */
+export const GameJournalEntryRecordSchema = object({
+    sequence: number(),
+    /** For display in a history list — a turn title, a chapter heading. */
+    name: string(),
+    data: optional(string()),
+    createdAt: string(),
+    updatedAt: string(),
+});
+/**
+ * Write one journal entry. Writing an existing `sequence` replaces it, which is
+ * how a turn is re-rolled or corrected without disturbing the ones after it.
+ *
+ * @example
+ * ```ts
+ * import type { GameJournalAppendRequest } from '@game-infra/game-state-schemas'
+ *
+ * const request: GameJournalAppendRequest = {
+ *   name: 'The tunnel breathes out ash',
+ *   data: JSON.stringify({ input: 'I follow the draught', narration: '…' }),
+ * }
+ * ```
+ */
+export const GameJournalAppendRequestSchema = object({
+    name: string(),
+    data: string(),
+});
+/**
+ * How far a journal delete reaches.
+ *
+ * - `entry` — that entry alone, for correcting one step in place.
+ * - `following` — that entry and every entry after it. This is undo: a journal
+ *   is folded in order, so keeping the tail after dropping a step in the middle
+ *   would replay effects that no longer have a cause.
+ */
+export const JOURNAL_TRUNCATIONS = ["entry", "following"];
+export const JournalTruncationSchema = picklist(JOURNAL_TRUNCATIONS);
+/**
+ * A journal position as it arrives in a path or query segment: digits, and
+ * short enough that no journal will ever reach it.
+ *
+ * Path segments are strings on the wire, so the shape is checked here — in the
+ * schema the contract references — rather than re-checked in every handler that
+ * reads one. Handlers take the number with `Number(...)`.
+ */
+export const SequenceParamSchema = pipe(string(), regex(/^\d{1,9}$/, "sequence must be a non-negative integer"));
+/** The caller's sessions for this game, most recently played first. */
+export const GameSessionListResponseSchema = createSuccessResponseSchema({
+    items: optional(array(GameSessionRecordSchema)),
+});
+/** One session header, absent when the caller has no session under that id. */
+export const GameSessionLoadResponseSchema = createSuccessResponseSchema({
+    item: optional(GameSessionRecordSchema),
+});
+/** The saved session's id, echoed back. */
+export const GameSessionSaveResponseSchema = createSuccessResponseSchema({
+    sessionId: optional(string()),
+});
+/** How many rows the delete removed — the session plus its journal entries. */
+export const GameSessionDeleteResponseSchema = createSuccessResponseSchema({
+    deletedCount: optional(number()),
+});
+/** A session's journal, in `sequence` order. */
+export const GameJournalListResponseSchema = createSuccessResponseSchema({
+    entries: optional(array(GameJournalEntryRecordSchema)),
+});
+/** The written entry's position, echoed back. */
+export const GameJournalAppendResponseSchema = createSuccessResponseSchema({
+    sequence: optional(number()),
+});
+/** How many entries the truncation removed — 0 when nothing matched. */
+export const GameJournalTruncateResponseSchema = createSuccessResponseSchema({
+    deletedCount: optional(number()),
+});
+//# sourceMappingURL=sessionState.js.map

package/dist/sessionState.js.map

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

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@game-infra/game-state-schemas",
+  "version": "0.1.0",
+  "description": "Play-state API contract: the sessions a player has in progress, the journal each one is rebuilt from, and freeform mode's turn and memory payloads",
+  "homepage": "https://github.com/kibertoad/game-infra/tree/main/packages/schemas/game-state-schemas#readme",
+  "bugs": {
+    "url": "https://github.com/kibertoad/game-infra/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kibertoad/game-infra.git",
+    "directory": "packages/schemas/game-state-schemas"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@toad-contracts/core": "0.4.0",
+    "@toad-contracts/valibot": "0.5.0",
+    "@game-infra/api-schemas-core": "0.3.0",
+    "@game-infra/event-schemas": "1.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "rimraf": "^6.1.3",
+    "typescript": "^7.0.2",
+    "valibot": "^1.4.2",
+    "vitest": "^4.1.10"
+  },
+  "peerDependencies": {
+    "valibot": "^1.4.0"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsc --project tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rimraf dist"
+  }
+}