@voltro/game-stack 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,225 @@
-# Temporary Holding Version
+# Game-stack composition
 
-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.
+The game stack composes existing game-system plugins through `gameStack()`. It
+is not yet the complete runnable `game` starter. No budget or capacity claim
+follows from this package.
+
+```ts
+import { gameStack, describeGameStack } from '@voltro/game-stack'
+import type { GameStackOptions } from '@voltro/game-stack'
+
+export const gamePlugins = (configuration: GameStackOptions) =>
+  gameStack(configuration)
+
+export const gameDependencies = (configuration: GameStackOptions) =>
+  describeGameStack(configuration)
+```
+
+## Visible ordinary plugin composition
+
+The result is a frozen array of ordinary `VoltroPlugin` objects for the normal
+`plugins` configuration. Each selected system invokes its actual single-plugin
+factory. Schema, routes, services, privacy, inspect endpoints and app-shaped
+sources stay owned by that plugin. The preset creates no second SQL path, private
+Runtime, pool, scheduler, host or data store. Its root entry is server-only;
+`./systems` and `./errors` contain browser-safe catalogue/diagnostic schemas;
+`./fight` is a separate pure gameplay reference entry.
+
+The typed fields are `auth`, `players`, `sanctions`, `social`, `chat`, `guilds`,
+`inventory`, `economy`, `progression`, `liveops`, `saves`, `rooms`, `matchmaking`,
+`leaderboards`, plus `preset` and `additionalPlugins`. Each system takes its real
+factory options or `false`. The actual optional-configuration factories for
+Players/Sanctions/Social/Chat/Guilds also accept `true` to use their own
+ordinary defaults. Strategy callbacks, custom Ports, schema declarations and
+provider participants are passed through the existing factory API, not translated
+into a second rule vocabulary. Factory validation remains authoritative. Rooms needs explicit
+options including `bindApi`: `roomsPlugin()` without a binding refuses to boot, so
+selecting Rooms without them reports `missing_configuration`.
+
+Guest `auth` uses the actual `guestAuthPlugin` options: project-owned tenant and
+actual secret source, not a boolean combined with invented social providers.
+Provider/account auth, CMS, notifications or app bridges can be explicit
+`additionalPlugins`. The guest plugin retains normal required-secret declaration
+and lifecycle validation; no secret is minted, read or copied by the preset.
+Missing production credentials still belong to normal boot validation.
+
+## Selection and removal diagnostics
+
+Six composition selectors are `arena`, `cards`, `quiz`, `world`, `fight`,
+`minimal`; default is `arena`. Non-minimal selectors currently select the fourteen
+meta/Rooms systems. `minimal` selects Guest Auth, Rooms, Matchmaking and Leaderboards.
+These selectors describe plugin composition only. They do not automatically install
+world/fight/reference-game simulations, renderer, screens or hosting artifacts.
+The optional explicit `./fight` reference is described below.
+Explicit configuration enables a system outside the selected set; `false` removes
+it. The preset never secretly adds a removed system. Every system can be removed,
+including all systems, which yields an empty plugin list.
+
+`describeGameStack()` returns only preset/system selection and deterministic
+`missing_configuration`/`missing_system` diagnostics. `./systems` exposes the
+same browser-safe catalogue through `GAME_SYSTEMS`, `GAME_SYSTEM_IDS`,
+`GAME_PRESET_IDS`, `presetGameSystems()` and `describeGameSystems()`. No probe,
+SQL read, service invocation, owner/provider data, options or credentials appear
+in diagnostics. The dependency list names program integration requirements;
+it does not infer that an external participant or policy is actually operating.
+Removed Social/Sanctions next to Chat/Matchmaking remain visible as diagnostics.
+
+Selected Guest Auth, Inventory, Economy, Progression, LiveOps, Saves, Matchmaking
+and Leaderboards require their actual author/project/content options. Missing
+configuration refuses with `GameStackError` before constructing any plugin. The
+complete default starter content that would make those fields accept `true`
+is still open; no empty currency/catalog/track/policy is fabricated. Dependency
+removal warnings do not add systems or silently supply successful guard callbacks.
+
+Root selection and extra-plugin arrays reject unknown fields, accessors, sparse
+entries and invalid selectors before invoking getters or constructing plugins.
+Additional plugins follow ordinary framework conventions. Duplicate final plugin
+names refuse. Selection is captured once; each actual factory owns capture and
+validation of its nested options. The resulting array preserves normal plugin
+objects/services rather than freezing private mutable runtime data.
+
+## Existing resource participants
+
+When both Inventory and a configured default Economy Shop are selected, the
+composer supplies the actual Inventory `prepareGrant` participant only if Shop
+has none. The normal prepared-unit contract requires the same physical SQL
+store. External Inventory replacements and different stores do not acquire a
+private default SQL adapter; the real participant refuses incompatible work.
+Explicit Shop participants and full root/Shop replacements retain precedence.
+Removing Inventory never silently reinstalls it.
+
+For an already configured Progression `delivery`, missing Inventory/Economy
+destinations borrow those selected plugins' actual service facades. Explicit
+ports and full root/delivery replacements win. No delivery, funding account,
+content, worker or self-XP destination is invented. Factory and port admission
+remain authoritative; an installed unavailable destination stays unavailable.
+
+Amounts/content are illustrative test-owned configuration, not commercial
+default prices. Direct fixture delivery is not durable workflow, guest/Gateway,
+compiled boot or whole starter evidence.
+
+The same missing-participant rule applies to configured Codes, Containers and
+Subscriptions using `prepareGrant`, and to Trades using the actual Inventory
+reservation/transfer/evidence methods. Absent child systems stay absent. This
+does not supply Trade authority, container eligibility/randomness or subscription
+consent; their existing factories require actual providers.
+
+A selected default LiveOps Inbox with an explicit nondefault `version` and no
+`grants` borrows the existing `economyInboxGrants` adapter from selected
+Inventory/Economy prepared facades. Its normal `inbox` funding namespace belongs
+to that adapter. An absent/explicit `default.v1` version retains the ordinary
+no-participant shape; explicit grants or full Inbox replacement win. Receipt,
+claim and all attached mutations share the ordinary physical-store SQL commit.
+Removing participants never installs private destinations.
+
+The resource fixture now includes real Codes redemption and Inbox currency/item
+claim with stable replay, foreign-tenant refusal and scoped privacy alongside
+Shop and Progression. Private redemption values are minted only at fixture
+execution.
+
+## Source Doctor and explicit file ownership
+
+`voltro doctor [app] --game [--json]` diagnoses the real source selection
+through the same catalogue without evaluating app configuration or probing
+participants. Normal Doctor also exposes this section. Dynamic selections are
+unavailable, never a claim that policies or workers are operating. `voltro game
+track`, `game remove` and `game restore` capture explicit ownership, plan/apply
+removal and restore retained source bytes only while their hashes agree. They
+are documented in [Game source commands](/docs/cli/game).
+
+## Authority and data boundaries
+
+`economy.realMoney:false` passes unchanged to the real economy factory, including
+its in-game price path. The preset invents no price, region, provider, currency,
+reward or successful grant callback. Real Room, Inbox, rating and other progression
+participants remain explicit actual bindings; their
+complete cross-system defaults and process proofs are not established here.
+Hot data and multi-node refusal remain the actual plugins' HotStore/Connection-
+Registry contracts. Tick simulation still belongs to the Rooms lane; this package
+has no tick executor or store operation.
+
+## Deferred verification and remaining construction
+
+A common actual four-plugin Players/Sanctions/Social/Chat fixture additionally
+exercises real bound SQL, installed Ports, route executors, block/mute refusal,
+tenant isolation, idempotent messages and coordinated erase. Fixture
+Subjects/lifecycle and a real single-node Memory HotStore do not establish
+normal guest/Gateway or Redis/ multi-node/production behavior. No fake SQL,
+worker, provider, Room or completed reward is used to claim a pass.
+
+The next construction joins actual starter content and durable cross-system
+participants, complete per-template manifests and focused shared source files,
+then real player/admin screens and whole-stack fixtures. Owner
+prices/regions/DNS/TLS/showcase/engine prerequisites remain explicit owner
+decisions.
+
+## Optional Fight reference sources
+
+The explicit browser-safe `@voltro/game-stack/fight` source entry adds a
+two-player reference on the actual Rooms fixed math and captured simulation.
+This entry installs no plugin, API binding, host, preset, renderer or transport.
+The `fight` composition selector still does not automatically install reference
+content.
+
+```ts
+import type { DeclaredAccess } from '@voltro/protocol'
+import { createFightRoom, createFightOptions } from '@voltro/game-stack/fight'
+import { createSimulationRunner } from '@voltro/plugin-rooms/simulation'
+
+export function fightReference(guards: DeclaredAccess,
+  serverSelectedPlayerIds: ReadonlyArray<number>) {
+  const room = createFightRoom({ guards })
+  const options = createFightOptions(serverSelectedPlayerIds)
+  const runner = createSimulationRunner(room.simulation, 42, options)
+  return { room, options, runner }
+}
+```
+
+The caller supplies its actual access declaration and server-selected public
+player IDs. `createFightOptions` captures exactly two distinct unsigned-32-bit
+IDs in canonical numeric order and owns complete tuning. State stores IDs as
+16-bit `hi`/`lo` words so even IDs above the signed state-integer range remain
+lossless. The reference refuses incomplete or foreign intent matrices while
+running. Its initial option IDs must match the real host's admitted roster;
+ordinary API/default allocation and template/bootstrap mapping remain open.
+The local runner example does not allocate Seats or authenticate players.
+
+`FightInputSchema` accepts only `move: -1 | 0 | 1`, `jump`, `strike` and `block`.
+Positions, velocity, health, stamina, facing, cooldown and round outcome come from
+the simulation. All spatial state uses Q16.16 raw integers. Movement is bounded
+by the stage, grounded jumps need a fresh button edge, gravity and ceiling/ground
+contact use the same fixed math, and body separation resolves in a canonical
+order. Strikes need a fresh button edge, stamina and an expired cooldown; even
+a whiff costs stamina. Blocking prevents striking and charges its actual cost
+when hit. Stun prevents the next configured action ticks.
+
+Both movement candidates are captured first. Both hit outcomes then see the
+same pre-damage target snapshots before either is applied, permitting a
+simultaneous knock-out draw. A timeout compares remaining health. Terminal
+state stays stable; its retained finish event must be consumed with an
+`elapsedTicks`/event-index cursor rather than emitted again for every snapshot.
+Per-transition `events` (`jump`, `strike`, `hit`, `block`, `finish`) are bounded
+authoritative state for observation outside simulation work, not an event-bus
+write or durable reward/sanction delivery. No Store/read/write enters the step.
+
+`defaultFightRules` is exported illustrative gameplay content.
+`createFightOptions(ids, partialRules)` changes raw speeds, stage/body sizes,
+range, damage, health/stamina/costs, cooldown/stun and round duration through
+strict own-data/range admission. Full rules are in the authoritative state and
+its hash, not hidden factory configuration. Rule ceilings and the reference's
+16-element collection, 4096-node, 65536-byte and field-ID64 limits are work
+budgets, not measured capacity or deterministic engine support.
+
+`createFightSimulation({ strategies: { movement, hit } })` accepts pure
+synchronous overrides. The exported `defaultFightMovement` and
+`defaultFightHit` can be composed directly. Contexts contain detached frozen
+fighters, rules and actual tick; outputs are exact bounded own data, copied
+before application. Promise outputs and malformed/getter outputs refuse.
+`describeFightStrategies` reports default/custom for that genuine descriptor
+only. Complete simulation replacement uses the actual captured `simulation`
+field of `createFightRoom`; simultaneous replacement and rule-slot overrides
+refuse ambiguous configuration. The factory requires a nonempty actual access
+declaration, defaults to a two-player `referee` Room, and passes normal
+lockstep, budget, tick-rate and reconnect options to the existing declaration.
+A different gameplay model can use ordinary `defineSimulation`/`defineRoom`
+without this optional reference. No new service Port is needed for this pure leaf.

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.