@voltro/plugin-saves 0.0.0-stage → 0.87.0

package/LICENSE

@@ -0,0 +1,61 @@
+Voltro — Proprietary Software License
+
+Copyright (c) 2026 Voltro UG. All rights reserved.
+
+This software and all associated source code, documentation, and other
+materials (the "Software") are the proprietary property of Voltro UG
+("Voltro"). This is NOT open-source software.
+
+Your access to and use of the Software is governed exclusively by the Voltro
+Terms of Service at:
+
+    https://voltro.cloud/legal/terms
+
+By downloading, installing, or using the Software you agree to those Terms.
+Subject to and conditioned on your continued compliance with them, Voltro
+grants you a limited, non-exclusive, non-transferable, non-sublicensable,
+revocable license to use the Software. The license covers use by your
+authorised named users only, up to the number of seats (or other billing metric)
+your plan or order covers; each named user must be an identified individual
+using their own personal account, and accounts, access credentials and seats
+must not be shared. All rights not expressly granted in the
+Terms are reserved by Voltro. If you do not agree to the Terms, you have no
+license and may not use the Software.
+
+The Terms of Service — including the scope of permitted use, plan
+entitlements, fees, and pricing — may change from time to time. The version in
+force is the one published at the URL above. Commercial terms and pricing are
+NOT part of this notice and are not fixed by, or granted in perpetuity by, the
+version of the Software in which this file appears.
+
+Permitted use — your own software. Voltro is a development framework. You may
+use the Software to build, run, and commercially distribute your own
+applications and services, and to charge your own customers for them, without
+owing Voltro any share of that revenue or any further permission beyond the
+Terms. Applications you build with the Software are yours.
+
+Prohibited use — reselling Voltro. You may NOT redistribute, resell,
+sublicense, publish, or otherwise provide the Software itself — in whole or in
+part, in source or compiled form — to third parties as a library, framework,
+SDK, template, starter, or development tool for them to build upon, whether
+standalone or repackaged. Shipping the Software as a non-separable, bundled
+dependency inside an application you deliver (for example, compiled into your
+deployed app) is permitted; extracting or re-exposing it as a reusable
+component for others is not.
+
+Except as expressly permitted above or by the Terms, you may not copy, modify,
+merge, publish, sublicense, sell, distribute, or create derivative works of the
+Software, in whole or in part.
+
+Third-party open-source components distributed alongside the Software are the
+property of their respective owners and are licensed under their own terms; see
+THIRD-PARTY-NOTICES.md where provided. Nothing in this notice limits your
+rights, or extends Voltro's, in those components.
+
+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
+VOLTRO BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM,
+OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.
+
+For licensing inquiries, contact Voltro UG.

package/README.md

@@ -1,3 +1,91 @@
-# Temporary Holding Version
+# @voltro/plugin-saves
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Use with matching unreleased source. No capacity or support claim follows.
+
+Owner-scoped opaque progress in one borrowed SQL store: monotonic slot versions,
+bounded history, basis conflicts, exact original-request replay and guest/user
+erase/export. The configured game and authenticated tenant/owner scope every
+operation; player input contains no owner selector or server value grant.
+
+```ts
+import { savesPlugin } from '@voltro/plugin-saves'
+import { memory } from '@voltro/kv/connection'
+
+export default {
+  name: 'save-api', type: 'api', store: 'sqlite',
+  connections: { redis: { local: memory() }, defaults: { redis: 'local' } },
+  plugins: [savesPlugin({ gameId: 'example.game', slots: ['main', 'profile-2'] })],
+}
+```
+
+The example's memory connection is single-node. Multi-node needs an actual
+cross-node Redis HotStore through the app ConnectionRegistry; memory refuses
+activation. SQL remains truth; quota state is never saved progress. Default
+write admission is ten requests per minute, with an inline byte budget of
+1 MiB, five retained versions and a seven-day deletion grace. These are
+configured budgets, not measured capacity or deployment recommendations.
+
+`./rpc` exposes paired `saves.get`, `saves.list`, `saves.history`, `saves.put`,
+`saves.rollback` and `saves.remove` descriptors. Reads list metadata without
+loading private blobs; get returns bytes through the existing Base64 wire
+schema. Put takes slot/requestId/baseVersion/schemaVersion/bytes/deviceId/
+clientVersion/summary. Rollback and remove take the original request/basis.
+Keep an uncertain intent and its original request ID; retry that same intent.
+Changing its content gives request_conflict. SaveConflict contains the current
+serverVersion plus server/client summaries; it never accepts client state as
+Wallet/Inventory/ranked authority. New acceptance always advances the version.
+
+`./web` exports useSave, useSaveSlots, useSaveHistory, usePutSave,
+useRollbackSave and useRemoveSave over the ordinary registered RPC group.
+No offline journal, conflict dialog or useSaveSync is installed yet.
+
+Take the default service through `SavesPort`; configure slots/body/history/
+request/grace budgets and an optional Effect JSON schema plus schemaVersion.
+Hook committed SQL changes with the actual borrowed store's onChange. Override
+the exported defaultSaveValidator using a named version and a pure validator;
+return exactly true to admit. It receives copied previous/proposed/decoded
+progress. Rollback obeys the current schema, body budget and validator.
+
+Replace the complete eight-method service with `service`, a non-default
+version and actual querySources. The replacement owns its store, work limits,
+privacy and policy; default SQL/HotStore/schema options are refused. Methods
+are captured once with their actual receiver; accessors are refused. The plugin
+still guards active lifetime, authenticated ownership and declared slots.
+
+`./testing` exports savesFixture, savesPortFixture, scoped savesFakeLayer,
+savesPortSystemFixture and saveValidatorSystemFixture. These use actual
+InMemoryDataStore/HotStore adapters and revoke escaped service access on close.
+The real systemContractConformance registration and six native-dialect suites
+pass in the current complete package suite on all six SQL dialects. These local
+checks do not establish production deployment or independent engine acceptance.
+
+The four SQL tables own heads/history/original receipts/permanent subject
+fences. onExport emits owner bytes as Base64 within explicit row/body limits.
+onErase removes private rows even if bytes are corrupt and retains an erased
+subject fence with ownerId null. Peers and foreign tenants stay independent.
+Soft deletion hides the head immediately and permits owner rollback only
+inside the grace. Expired private bytes are not purged automatically yet.
+
+The read-only status endpoint has all four dashboard layers and a single
+browser-safe canonical schema. It displays configured bounds and this process's
+activation only. Offline sync, signatures, external storage, expiry purging and
+GM rollback remain open. Docs: `/docs/plugins/saves`; thin `api-saves` template
+has passing rendered example tests, complete types and a production build.
+
+Production activation now source-checks the actual deployment-wide plugin grant.
+Declare actual Licensing first; development/test remains free. See the bilingual
+Licensing contract and manual update migration.
+
+## Activation and binding
+
+Both ordinary host orders are supported: activation before DataStore binding, or
+binding before activation. Ports and inspect bound readiness require both. A
+complete replacement cannot borrow early availability. Shutdown revokes the
+binding generation; reactivation requires explicit rebind to the same app store.
+SQL stores and registry connections remain borrowed. Production licensing still
+runs before authorized activation.
+
+Saves captures a call's generation at intention creation. Old effects cannot use a
+new binding after shutdown. Pending activation/owned cleanup fences new binding;
+failed drainage retains ownership and stays fenced. App-supplied HotStores are
+borrowed; only this instance's managed runtime is disposed.

package/SECURITY.md

@@ -0,0 +1,56 @@
+# Security Policy
+
+We take the security of Voltro and the applications built on it seriously. This
+document explains how to report a vulnerability and what to expect in return.
+
+## Reporting a vulnerability
+
+**Please do not open public issues or discuss suspected vulnerabilities in
+public channels.** Report them privately by email:
+
+**security contact: [support@voltro.dev](mailto:support@voltro.dev)**
+(subject line: `SECURITY`).
+
+Include, where you can:
+
+- the affected package(s) and version(s) (e.g. `@voltro/runtime@x.y.z`);
+- a description of the issue and its impact;
+- a minimal reproduction or proof of concept;
+- any suggested remediation.
+
+If you'd like to encrypt your report, ask in a first plain email and we'll
+arrange a key.
+
+## What to expect
+
+- **Acknowledgement** of your report within **3 business days**.
+- An initial assessment (severity, affected surface) and a remediation plan as
+  soon as we've reproduced the issue.
+- **Coordinated disclosure:** we'll agree a disclosure timeline with you and
+  credit you in the release notes if you wish. Please give us reasonable time to
+  ship a fix before any public disclosure.
+
+We do not currently run a paid bug-bounty program, but we genuinely appreciate
+responsible disclosure and will credit reporters.
+
+## Software Bill of Materials (SBOM)
+
+A CycloneDX SBOM of the third-party runtime dependency graph is generated for the
+published packages (`pnpm gen:sbom` → `sbom.cdx.json`). If your procurement or
+security team needs it, request it at
+[support@voltro.dev](mailto:support@voltro.dev).
+
+## Supported versions
+
+Voltro is pre-1.0 and ships in lockstep: **only the latest published minor of
+each `@voltro/*` package receives security fixes.** Please upgrade to the latest
+release before reporting, and pin exact versions in production.
+
+## Scope
+
+In scope: the published `@voltro/*` packages and the framework's own code.
+
+Out of scope: vulnerabilities in third-party dependencies that are already
+tracked upstream (we monitor these via a production-dependency audit gate in
+CI), and issues that require a non-default, explicitly-unsafe configuration. If
+you're unsure, report it anyway — we'd rather hear about it.