@voltro/plugin-saves 0.0.0-stage → 0.88.0

package/dist/testing.d.ts

@@ -0,0 +1,213 @@
+import { ConnectionRef } from '@voltro/kv/connection';
+import { Context } from 'effect';
+import { DataStore } from '@voltro/database';
+import { Effect } from 'effect';
+import { HotStoreShape } from '@voltro/kv/hot';
+import { Layer } from 'effect';
+import { PluginLifecycleContext } from '@voltro/protocol';
+import { PluginPrivacyTarget } from '@voltro/protocol';
+import { Schema } from 'effect';
+import { Subject } from '@voltro/protocol';
+import { VoltroPlugin } from '@voltro/protocol';
+import { YieldableError } from 'effect/Cause';
+
+declare class SaveConflict extends SaveConflict_base {
+}
+
+declare const SaveConflict_base: Schema.Class<SaveConflict, Schema.TaggedStruct<"SaveConflict", {
+    readonly serverVersion: Schema.Number;
+    readonly server: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean, Schema.Null]>>;
+    readonly client: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean, Schema.Null]>>;
+}>, YieldableError>;
+
+declare interface SaveDeleteIntent {
+    readonly slot: string;
+    readonly requestId: string;
+    readonly baseVersion: number;
+}
+
+declare type SaveDocument = typeof SaveDocumentSchema.Type;
+
+declare const SaveDocumentSchema: Schema.Struct<{
+    readonly bytes: Schema.Uint8ArrayFromBase64;
+    readonly slot: Schema.String;
+    readonly version: Schema.Number;
+    readonly schemaVersion: Schema.Number;
+    readonly byteLength: Schema.Number;
+    readonly checksum: Schema.String;
+    readonly deviceId: Schema.String;
+    readonly clientVersion: Schema.String;
+    readonly savedAt: Schema.Number;
+    readonly summary: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean, Schema.Null]>>;
+    readonly deletedUntil: Schema.NullOr<Schema.Number>;
+}>;
+
+declare type SaveError = SavesError | SaveConflict;
+
+declare type SaveHeader = typeof SaveHeaderSchema.Type;
+
+declare const SaveHeaderSchema: Schema.Struct<{
+    readonly slot: Schema.String;
+    readonly version: Schema.Number;
+    readonly schemaVersion: Schema.Number;
+    readonly byteLength: Schema.Number;
+    readonly checksum: Schema.String;
+    readonly deviceId: Schema.String;
+    readonly clientVersion: Schema.String;
+    readonly savedAt: Schema.Number;
+    readonly summary: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean, Schema.Null]>>;
+    readonly deletedUntil: Schema.NullOr<Schema.Number>;
+}>;
+
+export declare const savePutFixture: (patch?: Partial<SavePutIntent>) => SavePutIntent;
+
+declare interface SavePutIntent {
+    readonly slot: string;
+    readonly requestId: string;
+    readonly baseVersion: number;
+    readonly schemaVersion: number;
+    readonly bytes: Uint8Array;
+    readonly deviceId: string;
+    readonly clientVersion: string;
+    readonly summary: SaveSummary;
+}
+
+declare interface SaveRollbackIntent {
+    readonly slot: string;
+    readonly requestId: string;
+    readonly baseVersion: number;
+    readonly version: number;
+}
+
+declare class SavesError extends SavesError_base {
+}
+
+declare const SavesError_base: Schema.Class<SavesError, Schema.TaggedStruct<"SavesError", {
+    readonly code: Schema.Literals<readonly ["invalid_input", "invalid_record", "forbidden", "not_found", "erased", "limit_exceeded", "invalid_save", "rate_limited", "unavailable", "request_conflict"]>;
+}>, YieldableError>;
+
+export declare const savesFakeLayer: Layer.Layer<SavesPort, SavesError, never>;
+
+/** Registered actual DataStore adapter + actual HotStore memory admission. No native SQL or transport claim. */
+export declare const savesFixture: (store: DataStore, patch?: Partial<SavesPluginOptions>) => Promise<{
+    store: DataStore;
+    plugin: SavesPlugin;
+    service: SavesService;
+    hotStore: HotStoreShape;
+    now: () => number;
+    setTime: (value: number) => void;
+    user: (id?: string, tenantId?: string) => {
+        type: "user";
+        kind: "guest";
+        id: string;
+        tenantId: string;
+    };
+    close: Effect.Effect<void, never, never>;
+}>;
+
+export declare const savesFixtureLifecycle: PluginLifecycleContext;
+
+declare interface SavesOptions {
+    /** Server configuration, never a game/owner selector from the player. */
+    readonly gameId: string;
+    readonly slots?: readonly string[];
+    readonly maxBytes?: number;
+    readonly historyVersions?: number;
+    readonly maxRequests?: number;
+    readonly deleteGraceMs?: number;
+    readonly version?: string;
+    readonly validator?: SaveValidator;
+    readonly schema?: Schema.Top | undefined;
+    readonly schemaVersion?: number | undefined;
+    readonly now?: (() => number) | undefined;
+}
+
+declare interface SavesPlugin extends VoltroPlugin {
+    readonly saves: () => SavesService;
+}
+
+declare interface SavesPluginOptions extends SavesOptions {
+    readonly service?: SavesService;
+    /** Actual app-owned invalidation sources required by a complete replacement. */
+    readonly querySources?: readonly string[];
+    readonly connection?: ConnectionRef<'redis'>;
+    /** Private fixture or single-node app-owned HotStore; never disposed here. */
+    readonly hotStore?: HotStoreShape;
+}
+
+declare class SavesPort extends SavesPort_base {
+}
+
+declare const SavesPort_base: Context.ServiceClass<SavesPort, "@voltro/SavesPort", SavesService>;
+
+export declare const savesPortFixture: Effect.Effect<{
+    store: DataStore;
+    plugin: SavesPlugin;
+    service: SavesService;
+    hotStore: HotStoreShape;
+    now: () => number;
+    setTime: (value: number) => void;
+    user: (id?: string, tenantId?: string) => {
+        type: "user";
+        kind: "guest";
+        id: string;
+        tenantId: string;
+    };
+    close: Effect.Effect<void, never, never>;
+}, SavesError, never>;
+
+export declare const savesPortSystemFixture: Readonly<{
+    kind: "port";
+    tag: typeof SavesPort;
+    fakeLayer: Layer.Layer<SavesPort, SavesError, never>;
+    probe: {
+        run: () => Effect.Effect<{
+            original: boolean;
+            bytes: number[] | null;
+            erased: boolean;
+        }, SaveError, never>;
+        expected: {
+            original: boolean;
+            bytes: number[];
+            erased: boolean;
+        };
+    };
+}>;
+
+declare interface SavesService {
+    readonly get: (subject: Subject, slot: string) => Effect.Effect<SaveDocument | null, SaveError>;
+    readonly list: (subject: Subject) => Effect.Effect<readonly SaveHeader[], SaveError>;
+    readonly history: (subject: Subject, slot: string) => Effect.Effect<readonly SaveHeader[], SaveError>;
+    readonly put: (subject: Subject, intent: SavePutIntent) => Effect.Effect<SaveHeader, SaveError>;
+    readonly rollback: (subject: Subject, intent: SaveRollbackIntent) => Effect.Effect<SaveHeader, SaveError>;
+    readonly remove: (subject: Subject, intent: SaveDeleteIntent) => Effect.Effect<SaveHeader, SaveError>;
+    readonly exportSubject: (target: PluginPrivacyTarget) => Effect.Effect<unknown, SaveError>;
+    readonly eraseSubject: (target: PluginPrivacyTarget) => Effect.Effect<void, SaveError>;
+}
+
+declare type SaveSummary = typeof SaveSummarySchema.Type;
+
+declare const SaveSummarySchema: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean, Schema.Null]>>;
+
+declare interface SaveValidationContext {
+    readonly previous: SaveDocument | null;
+    readonly proposed: SavePutIntent;
+    readonly decoded: unknown;
+}
+
+declare type SaveValidator = (context: SaveValidationContext) => boolean;
+
+export declare const saveValidatorSystemFixture: Readonly<{
+    kind: "slot";
+    defaultImplementation: SaveValidator;
+    defaultProbe: {
+        run: () => Effect.Effect<boolean, never, never>;
+        expected: boolean;
+    };
+    overrideProbe: {
+        run: () => Effect.Effect<boolean | "unavailable" | "invalid_input" | "invalid_record" | "forbidden" | "not_found" | "erased" | "limit_exceeded" | "invalid_save" | "rate_limited" | "request_conflict", never, never>;
+        expected: string;
+    };
+}>;
+
+export { }

package/dist/testing.js

@@ -0,0 +1,116 @@
+import { savesError as e } from "./errors.js";
+import { SavesPort as t } from "./port.js";
+import { defaultSaveValidator as n, resolveSaveValidation as r } from "./strategies.js";
+import { savesTables as i } from "./tables.entity.js";
+import { savesPlugin as a } from "./plugin.js";
+import { makeMemoryHotStore as o } from "@voltro/kv/hot";
+import { Effect as s, Layer as c, Result as l } from "effect";
+import { ensureTableRegistered as u } from "@voltro/database";
+import { InMemoryDataStore as d } from "@voltro/runtime";
+// src/testing.ts
+var f = {
+	app: {
+		name: "saves-fixture",
+		type: "api",
+		voltroVersion: "0.83.1"
+	},
+	env: { NODE_ENV: "test" },
+	config: {},
+	logger: {
+		info() {},
+		warn() {},
+		error() {},
+		debug() {}
+	}
+}, p = (e = {}) => ({
+	slot: "main",
+	requestId: "fixture.put",
+	baseVersion: 0,
+	schemaVersion: 1,
+	bytes: Uint8Array.of(0, 1, 255),
+	deviceId: "fixture.device",
+	clientVersion: "fixture.client.1",
+	summary: { chapter: 1 },
+	...e
+}), m = async (e, t = {}) => {
+	i.forEach(u);
+	let n = 1e3, r = await s.runPromise(o()), c = a({
+		gameId: "fixture.game",
+		slots: ["main", "profile-2"],
+		now: () => n,
+		hotStore: r,
+		...t
+	});
+	return await c.bindDataStore?.(e), await s.runPromise(c.onActivate(f)), {
+		store: e,
+		plugin: c,
+		service: c.saves(),
+		hotStore: r,
+		now: () => n,
+		setTime: (e) => {
+			n = e;
+		},
+		user: (e = "fixture.owner", t = "fixture.tenant") => ({
+			type: "user",
+			kind: "guest",
+			id: e,
+			tenantId: t
+		}),
+		close: s.suspend(() => c.onDeactivate(f)).pipe(s.orDie)
+	};
+}, h = s.tryPromise({
+	try: () => m(new d()),
+	catch: () => e("unavailable")
+}), g = c.effect(t, s.acquireRelease(h, (e) => e.close).pipe(s.map((e) => e.service))), _ = Object.freeze({
+	kind: "port",
+	tag: t,
+	fakeLayer: g,
+	probe: {
+		run: () => s.scoped(s.gen(function* () {
+			let e = yield* t, n = {
+				type: "user",
+				id: "fixture.owner",
+				tenantId: "fixture.tenant"
+			}, r = p(), i = yield* e.put(n, r), a = yield* e.put(n, r), o = yield* e.get(n, r.slot);
+			yield* e.eraseSubject({
+				subjectId: n.id,
+				tenantId: n.tenantId,
+				kind: "guest"
+			});
+			let c = yield* e.get(n, r.slot).pipe(s.result);
+			return {
+				original: i.version === a.version,
+				bytes: o ? Array.from(o.bytes) : null,
+				erased: l.isFailure(c) && c.failure._tag === "SavesError" && c.failure.code === "erased"
+			};
+		}).pipe(s.provide(g))),
+		expected: {
+			original: !0,
+			bytes: [
+				0,
+				1,
+				255
+			],
+			erased: !0
+		}
+	}
+}), v = () => Object.freeze({
+	previous: null,
+	proposed: p(),
+	decoded: null
+}), y = Object.freeze({
+	kind: "slot",
+	defaultImplementation: n,
+	defaultProbe: {
+		run: () => s.sync(() => (r(v()), !0)),
+		expected: !0
+	},
+	overrideProbe: {
+		run: () => s.try({
+			try: () => (r(v(), () => !1), !0),
+			catch: () => e("invalid_save")
+		}).pipe(s.catch((e) => s.succeed(e.code))),
+		expected: "invalid_save"
+	}
+});
+export { p as savePutFixture, y as saveValidatorSystemFixture, g as savesFakeLayer, m as savesFixture, f as savesFixtureLifecycle, h as savesPortFixture, _ as savesPortSystemFixture };

package/dist/web.d.ts

@@ -0,0 +1,116 @@
+import { ActionState } from '@voltro/client';
+import { SubscriptionIdle } from '@voltro/client';
+import { SubscriptionState } from '@voltro/client';
+
+export declare const usePutSave: (apiName?: string) => ActionState<{
+    readonly schemaVersion: number;
+    readonly bytes: Uint8Array<ArrayBufferLike>;
+    readonly deviceId: string;
+    readonly clientVersion: string;
+    readonly summary: {
+        readonly [x: string]: string | number | boolean | null;
+    };
+    readonly slot: string;
+    readonly requestId: string;
+    readonly baseVersion: number;
+}, {
+    readonly slot: string;
+    readonly version: number;
+    readonly schemaVersion: number;
+    readonly byteLength: number;
+    readonly checksum: string;
+    readonly deviceId: string;
+    readonly clientVersion: string;
+    readonly savedAt: number;
+    readonly summary: {
+        readonly [x: string]: string | number | boolean | null;
+    };
+    readonly deletedUntil: number | null;
+}>;
+
+export declare const useRemoveSave: (apiName?: string) => ActionState<{
+    readonly slot: string;
+    readonly requestId: string;
+    readonly baseVersion: number;
+}, {
+    readonly slot: string;
+    readonly version: number;
+    readonly schemaVersion: number;
+    readonly byteLength: number;
+    readonly checksum: string;
+    readonly deviceId: string;
+    readonly clientVersion: string;
+    readonly savedAt: number;
+    readonly summary: {
+        readonly [x: string]: string | number | boolean | null;
+    };
+    readonly deletedUntil: number | null;
+}>;
+
+export declare const useRollbackSave: (apiName?: string) => ActionState<{
+    readonly version: number;
+    readonly slot: string;
+    readonly requestId: string;
+    readonly baseVersion: number;
+}, {
+    readonly slot: string;
+    readonly version: number;
+    readonly schemaVersion: number;
+    readonly byteLength: number;
+    readonly checksum: string;
+    readonly deviceId: string;
+    readonly clientVersion: string;
+    readonly savedAt: number;
+    readonly summary: {
+        readonly [x: string]: string | number | boolean | null;
+    };
+    readonly deletedUntil: number | null;
+}>;
+
+export declare const useSave: (slot: string | undefined, apiName?: string) => SubscriptionIdle | SubscriptionState<{
+    readonly bytes: Uint8Array<ArrayBufferLike>;
+    readonly slot: string;
+    readonly version: number;
+    readonly schemaVersion: number;
+    readonly byteLength: number;
+    readonly checksum: string;
+    readonly deviceId: string;
+    readonly clientVersion: string;
+    readonly savedAt: number;
+    readonly summary: {
+        readonly [x: string]: string | number | boolean | null;
+    };
+    readonly deletedUntil: number | null;
+} | null>;
+
+export declare const useSaveHistory: (slot: string | undefined, apiName?: string) => SubscriptionIdle | SubscriptionState<readonly {
+    readonly slot: string;
+    readonly version: number;
+    readonly schemaVersion: number;
+    readonly byteLength: number;
+    readonly checksum: string;
+    readonly deviceId: string;
+    readonly clientVersion: string;
+    readonly savedAt: number;
+    readonly summary: {
+        readonly [x: string]: string | number | boolean | null;
+    };
+    readonly deletedUntil: number | null;
+}[]>;
+
+export declare const useSaveSlots: (apiName?: string) => SubscriptionState<readonly {
+    readonly slot: string;
+    readonly version: number;
+    readonly schemaVersion: number;
+    readonly byteLength: number;
+    readonly checksum: string;
+    readonly deviceId: string;
+    readonly clientVersion: string;
+    readonly savedAt: number;
+    readonly summary: {
+        readonly [x: string]: string | number | boolean | null;
+    };
+    readonly deletedUntil: number | null;
+}[]>;
+
+export { }

package/dist/web.js

@@ -0,0 +1,4 @@
+import { useAction as e, useSubscription as t } from "@voltro/client";
+// src/web.ts
+var n = (e, n = "app") => t(n, "saves.get", { slot: e ?? "" }, { skip: e === void 0 }), r = (e = "app") => t(e, "saves.list", {}), i = (e, n = "app") => t(n, "saves.history", { slot: e ?? "" }, { skip: e === void 0 }), a = (t = "app") => e(t, "saves.put"), o = (t = "app") => e(t, "saves.rollback"), s = (t = "app") => e(t, "saves.remove");
+export { a as usePutSave, s as useRemoveSave, o as useRollbackSave, n as useSave, i as useSaveHistory, r as useSaveSlots };

package/package.json

@@ -1,6 +1,90 @@
 {
   "name": "@voltro/plugin-saves",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.88.0",
+  "description": "Owner-scoped opaque saves with SQL versions, original-intent receipts, history and privacy.",
+  "keywords": [
+    "voltro",
+    "typescript",
+    "framework"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://voltro.dev",
+  "bugs": {
+    "email": "support@voltro.dev"
+  },
+  "author": {
+    "name": "Voltro UG",
+    "url": "https://voltro.dev"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "default": "./dist/server.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "import": "./dist/errors.js",
+      "default": "./dist/errors.js"
+    },
+    "./rpc": {
+      "types": "./dist/rpc.d.ts",
+      "import": "./dist/rpc.js",
+      "default": "./dist/rpc.js"
+    },
+    "./port": {
+      "types": "./dist/port.d.ts",
+      "import": "./dist/port.js",
+      "default": "./dist/port.js"
+    },
+    "./strategies": {
+      "types": "./dist/strategies.d.ts",
+      "import": "./dist/strategies.js",
+      "default": "./dist/strategies.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "default": "./dist/testing.js"
+    },
+    "./web": {
+      "types": "./dist/web.d.ts",
+      "import": "./dist/web.js",
+      "default": "./dist/web.js"
+    },
+    "./package.json": "./package.json",
+    "./inspect": {
+      "types": "./dist/inspect.d.ts",
+      "import": "./dist/inspect.js",
+      "default": "./dist/inspect.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "@voltro/protocol": "0.88.0",
+    "@voltro/database": "0.88.0",
+    "@voltro/kv": "0.88.0",
+    "@voltro/client": "0.88.0",
+    "@voltro/runtime": "0.88.0",
+    "@voltro/plugin-licensing": "0.88.0"
+  },
+  "peerDependencies": {
+    "effect": "4.1.0",
+    "react": "^19.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}