@voltro/plugin-inventory 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,442 @@
-# Temporary Holding Version
+# @voltro/plugin-inventory
 
-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.
+## Contracts and content
+
+`defineItem` captures an item's stable ID, kind, schema version, stack/expiry/equipment rules, and Effect schemas. `itemContent` validates and detaches both static attributes and instance defaults; catalog JSON never contains a Schema object. The example values below illustrate a test item, not deployment balancing.
+
+```ts
+import { Schema } from 'effect'
+import { defineItem, inventoryPlugin, itemContent } from '@voltro/plugin-inventory'
+
+const potion = defineItem({
+  id: 'potion.small', kind: 'consumable', schemaVersion: 1,
+  stackable: true, maxStack: 10, tradable: false,
+  rarity: 'common', tags: ['potion'],
+  attributes: Schema.Struct({ potency: Schema.Number }),
+  instanceAttributes: Schema.Struct({}),
+  display: { nameKey: 'items.potion.small.name' },
+})
+const inventory = inventoryPlugin({ items: [potion], channel: 'live', locale: 'en' })
+const content = itemContent(potion, { potency: 1 }, {})
+// Add inventory to the API app's plugins array.
+// After normal store binding, a trusted server job imports [content]
+// through inventory.inventory.importCatalog(subject, scopedImport).
+```
+
+The `./items`, `./catalog`, `./strategies`, `./errors`, `./rpc` and `./web` entries are designed as browser-safe source. SQL lives in `./server`; `./cms` is server-only.
+
+## Catalog sources
+
+`CatalogSource` is a read-only Effect port: `read({ tenantId, channel, locale })` returns one immutable `{ revision, items }` snapshot. The default `dataStoreCatalog` adapter borrows the app's DataStore. Imports need a system Subject or an explicitly allowed service, capture the complete input, serialize through a tenant fence and publish one channel/locale head in the same transaction as its snapshot. IDs and versioned gameplay bindings remain in SQL after removal. A kind cannot be reused under the same ID, and an accepted version cannot silently change its gameplay contract. A new revision may change validated content values. Old snapshots remain available in SQL; replay acknowledges the original import and never moves the active head backwards.
+
+`cmsCatalogSource` in `./cms` reads only the `item` content type's **published** rows, explicitly filtered by tenant, site, environment and locale. Its `environments` option maps logical channels to existing CMS environments; it guesses no deployment names. Register `inventoryItemContentTables` and the normal CMS revision/reference tables, and use the existing CMS publish/release pipeline. `definitionJson` contains the serialized validated `CatalogItem`; `itemId` and `schemaVersion` must match it. The adapter refuses a malformed or oversized whole snapshot. Direct CMS reads currently validate against installed contracts; durable ID reuse admission, a typed catalog editor, release-channel promotion and CDC invalidation for replacement sources remain integration work. Use SQL imports for the written durable ID/version binding contract.
+
+The proposed `voltro inventory import` command is not implemented. The actual server import method is `inventory.inventory.importCatalog(subject, { tenantId, channel, locale, revision, items })`. No background cache or backend fallback is installed. Catalog I/O belongs at join/workflow/request boundaries, never inside a room tick.
+
+## Trusted operations and player intentions
+
+`inventory.inventory.service()` and the request `InventoryPort` expose the same implementation. `grant` and `consume` require an explicit owner, tenant, request ID, reason and reference. Only system/allowed-service Subjects can grant or consume. A grant validates instance attributes, fills compatible unlocked stacks and creates bounded overflow. `stackPolicy` output must conserve quantity and respect each cap; `expiryPolicy` resolves a grant-time deadline. Repeated accepted intentions return the original operation receipt; a changed intention under the same identity refuses. A pending admission is not accepted value.
+
+Players and guests get `inventory.mine`, `inventory.loadout` and the app-configured `inventory.catalog`. The sole player mutation is `inventory.equip`: slot set, slot, instance ID or null, and request ID. The service derives tenant/owner from the verified Subject, checks possession, lock, deadline and the declared equipment slot, and never accepts quantities, attributes or client state. Declare `slotSets` to admit equipment. `useInventory`, `useLoadout` and `useCatalog` use the normal client subscription surface.
+
+`expire` is a trusted operation with an explicit cutoff and request ID. Reads hide overdue instances without writing; the job removes them and stale loadouts with `expired` ledger rows. Locked overdue instances refuse the operation. Scheduling that job and trade escrow integration remain open.
+
+The `inventory.equip` intention uses an action descriptor because the borrowed InventoryPort owns its complete SQL transaction. The dispatch spine adds no outer mutation transaction. The name and input remain the same; compiled dispatch and wire proof are pending.
+
+## SQL truth, rebuild and privacy
+
+The five owned roles are subject fences, item instances, loadouts, movement ledger and operation receipts. Each accepted operation allocates a durable owner sequence, so equal timestamps cannot scramble replay. Movement rows preserve validated after-images. `auditInventory` and `rebuildInventory`, exposed on the installed SQL facade and standalone adapter, replay complete accepted receipts/movements to compare or repair possession materialization; they refuse broken sequence, receipt, quantity or attribute evidence. Repair writes no new movement and never grants extra value. Loadouts remain separate SQL truth; the possession rebuild removes only dangling references and does not reconstruct equipment history.
+
+Default whole-work limits are 4,096 instances, 10,000 ledger/request rows, 10,000 catalog items and 10,000 persisted catalog versions. Limits are configurable within admitted ranges and overflow refuses; they are **not capacity measurements**. One attribute object is bounded to 4,096 nodes, depth 16 and a conservative 64-KiB string budget. Canonical hashing of whole work additionally refuses over 3,000,000 nodes, depth 32 or 64 MiB. No nightly evidence or production capacity follows from these budgets.
+
+The privacy declaration covers every table registered by the plugin, including shared catalog roles. Subject hooks retain shared tenant catalog content used by other players. User/guest export is tenant-scoped and contains only the subject's possessions, loadouts and movements. Erase fences later grants, removes possessions/loadouts, tombstones all owner-keyed request bodies including zero-change requests, and redacts retained ledger owner/instance/snapshot/reference/actor fields. Retained deterministic keys are pseudonymous. Guild-member privacy, arbitrary actor/reference erasure, account merge and a legal retention decision remain open.
+
+## Extension and inspect surfaces
+
+Exported `defaultStackPolicy` and `defaultExpiryPolicy` are the actual defaults. `./testing` supplies fixtures that call the actual item/content/strategy implementations. `catalogSource` and `service` replace the source and eight-method InventoryPort implementation; the replacement must retain authority, receipts and export/erase behavior. Full replacement-table privacy wiring, events, mixins, `craftResolver` and `systemContractConformance` remain open.
+
+The `/status` inspect endpoint and shared/local/cloud panels show process binding, installed source/stack/expiry slots, item contracts, slot sets and configured bounds. They contain no player inventory or ledger data. Search and page controls bound contract rendering. The four layers are written; their builds, transport and browser evidence are pending. Player lookup, ledger/reference search, channel diff and authorized grant/revoke/reset actions are not yet built.
+
+## Optional immediate item crafting
+
+`crafting` installs the four-method `CraftingPort` (`craft`, `recipes`, `exportSubject`, `eraseSubject`) alongside the existing eight-method InventoryPort. With the option absent, no recipe role or Crafting Layer is registered. Craft is trusted system/explicit-service only; the player API retains read/equip intentions. The following quantities are illustrative app recipe rules, not pricing or measured throughput. `potion` is the app's admitted item contract.
+
+```ts
+import { inventoryPlugin, defineRecipe } from '@voltro/plugin-inventory'
+import { systemSubject } from '@voltro/protocol'
+
+const distill = defineRecipe({
+  id: 'distill', version: 1,
+  inputs: [{ itemId: potion.id, qty: 2 }],
+  outputs: [{ itemId: potion.id, qty: 1 }],
+  maxBatches: 10,
+})
+const inventory = inventoryPlugin({
+  items: [potion], crafting: { recipes: [distill] },
+})
+// Invoke from trusted server code after normal app/store/catalog binding:
+const receipt = inventory.inventory.crafting().craft(systemSubject('inventory.craft'), {
+  tenantId, owner: { ownerKind: 'player', ownerId },
+  recipeId: distill.id, batches: 1, requestId,
+})
+```
+
+`defineRecipe` captures immutable ID/version, unique item inputs/outputs, optional JSON output attributes and a bounded batch count. The adapter is immediate: currency `cost` requires the exact-store prepared participant described below; positive `timeMs` or nonnull level/quest `requires` refuse admission. No charge, waiting timer or eligibility result is silently skipped. Each declared amount times the configured batch budget must fit the exact item quantity limit. Timed and prerequisite crafting still need actual Progression/workflow integration.
+
+`defaultCraftResolver` selects oldest eligible acquisitions, with deterministic ID ties. Equipped, locked and expired instances are excluded. Custom `craftResolver` receives detached frozen actual inventory observations and can select eligible instances or schema-valid output attributes; it cannot change declared input/output totals or add a gift. Custom craft/stack/expiry policies require an explicit nondefault `crafting.version`. Defaults and `craftFixture` are exported through `./crafting` and `./testing`. The existing Item contracts validate produced attributes and stack capacity; previous contract versions must remain while possessions reference them.
+
+The actual SQL adapter captures catalog content, craft selection, stack/expiry results and complete materialization basis outside replayable SQL callbacks. Immutable tenant/version recipe declarations live in `_voltro_inv_recipes`; changed declarations/rule versions refuse. Under the existing permanent Inventory owner fence, a changed sequence/item/loadout basis refuses the prepared plan. Accepted consumption, output creation/stack updates, append-only movements, operation receipt and captured craft intent commit together. A rejected plan cannot partially consume items. A retry of the same accepted request returns before catalog/clock/custom callbacks; changed intent under the same request conflicts. Distinct requests may craft independently. There is no room tick I/O or another state store.
+
+`auditInventory`/`rebuildInventory` validates recipe identity, captured request/digest, accepted input selection, exact output conservation and every movement/after-image. It uses accepted SQL truth without recalling historical craft/catalog/expiry/stack callbacks. Retained recipe declarations are shared configuration. Export includes owned craft intention/selection and the complete Inventory movement scope; erase clears owner/request/craft/receipt/link bodies, removes possessions/loadouts and preserves permanent pseudonymous fences. A delayed craft cannot revive an erased owner. Guild-owner lifecycle integration remains part of the outstanding complete Inventory contract.
+
+`crafting.service` replaces all four methods. A replaced InventoryPort requires a full Crafting service replacement; default SQL craft does not borrow custom storage. Replacement methods preserve their receiver and the plugin forwards complete export/erase. App-owned replacement tables still need explicit schema/CDC/privacy registration. The configuration-only inspect endpoint, Shared EN/DE semantic panel and ordinary Local/Cloud providers show actual optional backend/resolver/recipe budgets and report configured game-currency costs; duration workflow, prerequisites, player craft and trade/escrow remain absent. Captured configuration is not execution evidence.
+
+A six-dialect native case uses actual schema, independent borrowed pools, same-request concurrency, terminal replay, rebuild and erase. Factory/privacy, strict host decoder/provider and bilingual DOM regressions are written.
+
+## Prepared SQL inventory units
+
+`InventorySqlService.prepareGrant` and `prepareCraft` on the explicit
+`dataStoreInventory` server adapter prepare trusted intentions for
+`executeSqlMutations` from `@voltro/database/sql`. The units are bound to the exact
+borrowed store; InventoryPort and CraftingPort retain their ordinary methods.
+Grant/catalog/attribute/expiry and custom stack planning occur before acceptance.
+Default stack arithmetic runs under the owner fence; captured custom stock or
+craft basis changes refuse. Ordinary writes use the same single movement writer.
+
+Compose a debit and grant/craft outside an active transaction: a later failure
+rolls back all accepted movements, stock, wallet values and receipts together.
+Pending admissions are not accepted value. Recreate units from original SQL
+identities, never serialized capabilities. Terminal replay precedes clock,
+catalog and custom callbacks. Currency-cost recipes use the actual atomic
+participant described below; optional Shop binding is explicit in Economy, and
+does not borrow SQL for replaced ports. See the Transactions page in the
+bilingual public docs.
+
+
+The installed default SQL facade also exposes `inventory.inventory.prepareGrant`
+/ `prepareCraft`. These use the actual bound adapter, capture before laziness
+and revoke on deactivation. Replaced Inventory or crafting refuses SQL
+participation; no fallback. For Shop configuration pass `inventory.inventory` as
+the explicit `shop.inventory` participant. Independent exact-store admission
+protects against cross-app units.
+
+
+## Atomic game-currency crafting
+
+Immediate recipes may now declare `cost: { currency, amount }`, with a positive
+canonical decimal-string amount per batch. Full configured batch multiplication
+must fit signed SQL BIGINT. Free recipes use `cost:null`. Currency-cost recipes
+require an explicit exact-store `crafting.economy.prepareTransfer` participant
+unless the entire Crafting service is replaced. Missing participants refuse
+configuration; costs are never skipped. Positive duration or level/quest
+prerequisites still refuse. Amounts below are illustrative game rules, not Owner
+prices or measured budgets.
+
+```ts
+import { economyPlugin } from '@voltro/plugin-economy'
+import { defineItem, defineRecipe, inventoryPlugin } from '@voltro/plugin-inventory'
+import { Schema } from 'effect'
+
+const potion = defineItem({ id: 'potion', kind: 'consumable', stackable: true,
+  maxStack: 10, tradable: false, rarity: 'common', tags: [],
+  attributes: Schema.Struct({}), instanceAttributes: Schema.Struct({}),
+  display: { nameKey: 'items.potion' } })
+export const economy = economyPlugin({
+  currencies: [{ id: 'gold', kind: 'soft', cap: '1000' }], realMoney: false,
+})
+export const inventory = inventoryPlugin({ items: [potion], crafting: {
+  economy: economy.economy,
+  recipes: [defineRecipe({ id: 'distill', inputs: [{ itemId: potion.id, qty: 2 }],
+    outputs: [{ itemId: potion.id, qty: 1 }],
+    cost: { currency: 'gold', amount: '7' }, maxBatches: 10 })],
+} })
+// Add both instances to one API app; publish actual matching item content.
+// Only trusted server code invokes inventory.inventory.crafting().craft.
+```
+
+The installed default `economy.economy.prepareTransfer` facade borrows its actual
+SQL writer, captures inputs before laziness and refuses before binding, after
+deactivation or with a complete wallet replacement. It supplies no default SQL
+fallback for custom wallets. An explicit `EconomySqlService` also satisfies the
+structural participant. Inventory imports no Economy implementation at runtime.
+Full Crafting replacement owns its payment/privacy behavior; it cannot combine
+with a default currency participant or system-account option.
+
+The Inventory writer prepares the actual movement and wallet units outside SQL
+callbacks. One exact-store group accepts the wallet debit, item consumption,
+outputs, balanced financial postings, inventory movements and both actual
+receipts together. The sink defaults to `crafting` and can be named through
+`crafting.systemAccount`. The payment request derives from tenant/owner/original
+craft request, independent of mutable content. Ordinary and prepared craft use
+the same group and original writers, without nested service transactions. A
+foreign physical store is refused. Insufficient funds or a later movement/basis
+conflict rolls back accepted debit and outputs; pending admission rows are not
+paid or crafted value. Retrying uses the original request identity.
+
+Accepted craft SQL history retains the captured recipe/cost and actual payment
+receipt. Terminal replay validates it before current clock/catalog/resolver or
+payment preparation. Inventory audit/rebuild admits exact paid amount and unique
+payment identity while reconstructing items without another debit or historical
+callback. This is item history validation; Economy owns its complete financial
+ledger audit/rebuild. Erasing Inventory clears owned paid craft bodies; Economy
+must run its own privacy hooks to clear the wallet links. Shared recipe rules
+remain, and permanent owner fences refuse recreation. Receipt times describe
+captured admissions; no measured execution-duration claim follows.
+
+All four configuration inspect layers now include exact declared per-batch costs
+and whether currency fulfillment is configured. They expose no balance, payer,
+financial receipt or outcome. Time/prerequisite/player-craft/trade features
+remain absent.
+
+## Player inventory components
+
+The separate browser `./components` entry contains `InventoryGrid`, `ItemCard`,
+`LoadoutEditor` and `CraftingPanel`; React is required only for this entry/web
+hooks. Import the existing UI kit theme and include this package's source
+classes in the app's Tailwind sources.
+
+`InventoryGrid` accepts own instance/catalog observations and a caller-owned
+`at` timestamp. One detached pure admission joins content by item ID/schema
+version and refuses duplicate/malformed/getter-backed data. Removed catalog
+content retains visible possession IDs and quantities; unavailable metadata never
+permits equipment selection. Search and tags filter the actual content. Fixed
+rows/overscan keep DOM bounded; focused rows remain mounted, and Show all items
+provides complete traversal. Counts describe the current filtered data, not a
+measured capacity. A failed observation hides stale choices. Dates update only
+when the app supplies a new timestamp; no background polling or tick I/O.
+
+`LoadoutEditor` uses the live accepted loadout, declared slot set/slots and actual
+own catalog/items. It emits only `{ slotSet, slot, instanceId, requestId }`, with
+an app-owned identity and no owner/quantity/attribute data. The native select
+stays controlled by the accepted server observation; no optimistic item or
+loadout patch. Locked/expired/unknown or wrong-slot items cannot be selected.
+`useInventoryEquip` calls the existing action; failures belong to the parent's
+error handling. Subscription freshness/account-boundary ownership remains the
+application's responsibility.
+
+```tsx
+import { InventoryGrid, LoadoutEditor } from '@voltro/plugin-inventory/components'
+import { useInventory, useCatalog, useLoadout, useInventoryEquip } from '@voltro/plugin-inventory/web'
+
+export const Equipment = (props: { at: number; title: (key: string) => string; onError: (error: unknown) => void }) => {
+  const source = useInventory(), catalog = useCatalog(), loadout = useLoadout('arena'), equip = useInventoryEquip()
+  return <>
+    <InventoryGrid source={source} catalog={catalog} at={props.at} title={props.title} />
+    <LoadoutEditor source={source} catalog={catalog} loadout={loadout}
+      slotSet="arena" slots={['head']} at={props.at} title={props.title}
+      busy={equip.pending} requestId={() => crypto.randomUUID()}
+      onEquip={input => { void equip.run(input, { onError: props.onError }) }} />
+  </>
+}
+```
+
+`ItemCard` inherits the UI kit and accepts title/image slots, without inventing
+item art or resolving storage URLs. EN/DE copy and a complete copy override are
+available. `CraftingPanel` is read-only by default: local batch selection previews
+conserved ingredients through the actual exported craft resolver, excludes
+locked/expired/equipped material, and displays exact decimal currency costs.
+Materials available does not mean wallet affordability or reservation. An app
+may provide `renderAction` for its own authorized intention boundary; the package
+adds no player Craft/Grant RPC. Recipe costs/duration/prerequisites obey the
+actual partial server contract. Native SQL ownership remains on the server.
+
+DOM seams do not prove native layout, focus/accessibility, cross-account
+subscriptions, browser transport or actual large-list performance. Full
+player-template/Rooms integration remains open.
+
+## System contract port and strategy fixtures
+
+`./testing` now exports `inventoryPortFixture(options)`, `inventoryFakeLayer`,
+`craftingFakeLayer`, `inventoryPortSystemFixture`, `craftingPortSystemFixture`
+and the distinguishing `stackPolicySystemFixture`/`expiryPolicySystemFixture`/
+`craftResolverSystemFixture`. Their defaultImplementation fields refer to the
+actual exported defaults. Probes call the real admission/resolver functions; no
+copied stack/expiry/craft rule. They match the existing testing system suite's
+structural fixture contract, not a completed conformance run.
+
+The explicit test-only Layer acquires the real installed Inventory service and
+free Crafting on one new private InMemoryDataStore per scope, publishes the supplied
+actual content and provides the ordinary Tags together. Release is registered
+before binding/content preparation, and revokes the installed facade after scope
+exit, including failed setup. Item contracts/content/options are captured before
+Layer acquisition. No paid recipe is accepted by this fixture; actual paid native
+fixtures live with the real cross-system Economy participant. No independent
+wallet, fake SQL result, runtime backend or production isolation proof.
+
+`./testing` is a server/testing entry because these Layers load the actual
+adapters; never import it from a browser descriptor. Existing declaration
+fixture exports remain the same public names. Native SQL/durability/normal boot
+are not established by private memory stores. Full per-table privacy,
+events/hooks, inspect, table mixins/removal/upgrade and
+`systemContractConformance` registration/execution remain open; exported fixture
+presence is not a Plan21 pass.
+
+## Actual installed Catalog fixture
+
+The test-only `inventoryPortFixture` now builds the plugin's actual service Layer, including `CatalogSource`. Without recipes it exposes only Inventory/Catalog; an explicit empty recipe list refuses, and nonempty free recipes also expose Crafting. No absent Crafting service is synthesized. `catalogFakeLayer` and `catalogSourceSystemFixture` exercise the actual published scoped catalog. Catalog and mutation facades refuse after release.
+
+## Trusted Inventory reservation participant
+
+The default server adapter and installed facade now expose `prepareReserve`,
+`prepareRelease` and read-only `reservation`. `InventorySqlService` types and
+`InventoryReserveInput`, `InventoryReleaseInput`, `InventoryReservationView` are
+exported from `@voltro/plugin-inventory/server`; the public eight-method
+InventoryPort and sole player equip mutation remain the same. The facade refuses
+borrowing default SQL from a replaced Inventory service and refuses after normal
+deactivation. It captures input descriptors without invoking getters.
+
+A trusted system/allowed-service operation supplies tenant, actual owner,
+permanent reservation ID and unique instance quantities. The existing owner
+fence and movement writer validate actual inventory, catalog version/tradability,
+quantity, deadline and absence of another lock or loadout. Catalog/clock reads
+happen before replayable SQL. Every captured actual before-image is compared
+again under the transaction fence. Partial quantities conservatively lock the
+whole stack; the accepted reservation records the exact proposed quantity.
+Consume, equip, expiry and crafting cannot use that locked stack. No quantities,
+attributes, instance identity, acquisition or original expiry are regenerated.
+
+Canonical reserve/release operation identities derive from tenant/owner and
+reservation ID, independently of a caller nonce. The nullable server-only
+`reservation` field in the existing operation role holds admitted terms,
+versioned catalog content and before-images. Lock changes, zero-quantity movement
+snapshots, sequence and accepted receipt commit together through the actual
+`PreparedSqlMutation`/`executeSqlMutations` path. A group failure rolls back all
+accepted locks, snapshots, counts and receipts; pending rows can remain.
+
+Release requires this exact accepted reservation and actual unchanged locked
+instances. It unlocks the entire reserved stack even after the original expiry,
+so the normal expiry job can remove it. Reserve/release retries return originals
+before current clock/catalog; changed reserve terms under the same ID conflict.
+Replaying a released reservation's original receipt never locks the stack again.
+`reservation` reports accepted SQL custody snapshots (`not-observed`, `reserved`,
+`released`), not a fresh availability or balance claim. It performs only reads,
+without seeding, clock/catalog callbacks or materialization repair.
+
+Audit/rebuild validates the complete existing owner sequence, bound intention,
+exact canonical operation/digest, versioned tradable content, original before-
+images, zero deltas, lock transitions, matching release and movement references.
+Missing/mismatched custody refuses; repair uses accepted history without recalling
+historical callbacks. Export includes owned custody; erase clears reservation
+bodies, accepted snapshots and references alongside the existing owner privacy
+and keeps the permanent erased fence. Other owners and shared catalog remain.
+Guild lifecycle and arbitrary actor/reference erasure remain separate open scope.
+
+They cover original retries, grouped rollback, expired release, rebuild,
+privacy, accessor refusal, replacement borrowing and revocation. This
+participant does not install player trading: the four existing inspect layers
+keep `tradingInstalled:false`. Trade integration of the instance-preserving
+owner transfer/splitting participant below, Trade binding of the Wallet Escrow
+participant, Trade service/routes, expiry scheduling, replacement
+participant/conformance, cross-system hooks and templates remain open.
+
+## Original instance and partial reservation transfer
+
+`InventorySqlService.prepareReservationTransfer` and
+`inventory.inventory.prepareReservationTransfer` take trusted tenant, source
+owner, recipient owner and the existing permanent reservation ID. Types
+`InventoryReservationTransferInput` and `InventoryReservationTransferReceipt`
+are exported from `./server`. No new player write or InventoryPort method is
+introduced. The default-only facade captures the owners before laziness, refuses
+input getters/unknown state, replacement SQL borrowing and deactivated access.
+
+The actual owning writer derives quantities/content from the accepted reservation,
+never caller values. A whole reserved instance moves with its original ID. A
+partial transfer gives the recipient a deterministic split ID, leaves the source
+remainder under the original ID and unlocks it. Both retain exactly the existing
+schema, attributes, acquisition time, original expiry and provenance. No new
+grant, stack-policy call, catalog/expiry callback or asset creation authority is
+used. Expired assets refuse transfer; the matching release remains available.
+
+The prepared exact-store group fences both owners in deterministic key order,
+executes outgoing and incoming operations through the same movement writer and
+checks their actual reciprocal receipts before commit. Source delta plus target
+delta is zero per item. Recipient capacity, unchanged actual reserved stock,
+loadouts, quantity, deadline and canonical operation/target/split identity remain
+mandatory. Failure rolls back both possessions, locks, sequences, movements and
+accepted receipts; pending admissions may remain. Changed recipients conflict
+with the source's permanent transfer identity. Accepted retries use original
+reservation and both receipts before current clock/catalog, without recrediting.
+An erased participant refuses replay; no re-creation bypass is provided.
+
+The existing operation role adds nullable server-only `transfer` custody. Each
+owner's admitted intention contains only that owner's raw ID and the opaque
+counterpart fence/operation keys, plus original asset snapshots. These keys are
+pseudonymous, not anonymization. The shared owner movement/receipt sequence now
+recognizes `transfer-out` and `transfer-in`. Audit/rebuild validates original
+reservation/lock transition, exact before/after snapshots and both immutable
+movement IDs/deltas. Incoming history preserves original acquisition rather than
+reassigning it to the transfer time. Missing peer rows, movements, mismatched
+quantities or snapshots refuse. Owner erasure clears its own transfer bodies,
+instance/reference/actor fields and after-images; retained counterpart operation
+sequence and item deltas prove conservation for the surviving owner's rebuild.
+An erased owner's materialization cannot be recreated. Arbitrary actor/reference,
+app-specific attribute privacy, guild lifecycle and legal retention remain open.
+
+Read-only `reservation` adds `transferred`, with an empty current-custody list,
+when both accepted journal sides establish transfer. It never reports the
+original locked snapshot as freshly available after transfer. It still performs
+only reads. The four inspect layers retain `tradingInstalled:false`: Trade
+binding of the Wallet Escrow participant, Trade service and player accept/cancel
+routes, sanctions/source integration, replacement transfer participant, hooks,
+expiry jobs and templates remain open.
+
+## Atomic fresh reservation and transfer
+
+`InventorySqlService.prepareReserveTransfer` and the default-only lifecycle
+facade capture `InventoryReserveTransferInput` (tenant/from/to/reservation/items).
+`InventoryReservedTransferReceipt` contains actual `reserve` and `transfer`
+receipts. They use the same reservation/paired-transfer/movement writers, one
+exact-store SQL group and two deterministic owner fences. Fresh counterparty
+items need no earlier accepted reservation transaction. Whole original IDs or
+exact split quantities preserve attributes, acquisition, provenance and original
+expiry. Catalog/before-images are captured outside SQL and rechecked under fences.
+A changed/raced basis refuses; no callback or new catalog source is called in
+replayable SQL. Originals precede current clock/catalog; no renewed expiry.
+
+Failure rolls back fresh locks, both movement sides, sequences and accepted
+custody/receipts together. Pending admissions can remain. Existing cap, capacity,
+expiry, ownership and privacy rules apply; no final-position capacity netting is
+inferred. Inputs are trusted system/allowed-service only, descriptor-captured and
+revocable; no InventoryPort/player method is added. Missing accepted custody is
+refused, not repaired. The higher-level Trade writer must bind immutable terms
+and actual sanctions/admission to the same group.
+
+No new table or installed Trade service; `tradingInstalled:false` remains
+accurate until full durable Trade binding/routes/panels are installed.
+
+## Read-only original reservation evidence
+
+Trusted `InventorySqlService.reservationEvidence` and the default-only revocable
+facade return `InventoryReservationEvidence` through the same actual
+reservation/ peer validation as `reservation`. It includes original selected
+items, actual reserve/release and transfer-from/to receipts. Unlike current
+availability, its `items` remain original custody snapshots after
+release/transfer. They are not spendable stock. A redacted peer receipt is null;
+retained peer conservation is still checked. No synthetic receipt is recreated.
+
+Observation invokes no seed, current clock/catalog, repair or writer. Existing
+availability `reservation` shape stays unchanged and shows empty items after
+close. Native/root Trade source scenarios reuse this real read.
+
+### Prepared consumption for cross-system financial groups
+
+The server SQL adapter exposes `InventorySqlService.prepareConsume(subject,
+input)` alongside `prepareGrant`. It captures the same trusted consume intention
+and returns an actual-store-bound participant in the existing movement writer.
+Ordinary `consume` executes this same writer. The ordinary eight-method
+`InventoryPort` and player equip intention stay unchanged. A group failure rolls
+back accepted consumption and movement receipts; pending admissions may remain.
+The Economy IAP asset adapter uses this participant for explicit item-refund
+disposition.
+
+
+## Production license admission
+
+Declare the actual `licensingPlugin()` before this plugin in the API app. Production and staging activation require its verified active or grace deployment-wide license to grant `inventory`. Explicit development/test mode stays free without recurring per-instance notices; CLI owns the actual template first-boot receipt. Tenant-scoped licenses refuse until actual tenant-bound authority exists. This server-only gate preserves normal schema, store binding and cleanup; it runs before the original activation hook, not before schema/store binding.
+
+## Responsive filters
+
+InventoryGrid stacks its labeled search, tag and traversal controls on narrow
+screens and uses a flexible three-column row from the small-screen breakpoint.
+The minimum control height stays 44 px; filtering and server-controlled inventory
+behavior are unchanged.

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.