@voltro/plugin-inventory 0.0.0-stage → 0.88.0

package/dist/server.d.ts

@@ -0,0 +1,816 @@
+import { ColumnBuilder } from '@voltro/database';
+import { DataStore } from '@voltro/database';
+import { Effect } from 'effect';
+import { FieldDefinitions } from '@voltro/database';
+import { PluginPrivacyTarget } from '@voltro/protocol';
+import { PreparedSqlMutation } from '@voltro/database/sql';
+import { Schema } from 'effect';
+import { Subject } from '@voltro/protocol';
+import { Table } from '@voltro/database';
+import { YieldableError } from 'effect/Cause';
+
+export declare interface CatalogImport extends CatalogScope {
+    readonly revision: string;
+    readonly items: readonly CatalogItem[];
+}
+
+/** Serializable content uses a declared item's version, never a stored Schema object. */
+declare interface CatalogItem {
+    readonly id: string;
+    readonly schemaVersion: number;
+    readonly kind: ItemKind;
+    readonly stackable: boolean;
+    readonly maxStack: number;
+    readonly tradable: boolean;
+    readonly rarity: string;
+    readonly tags: readonly string[];
+    readonly equipSlot: string | null;
+    readonly expiresAfter: number | null;
+    readonly display: {
+        readonly nameKey: string;
+        readonly icon: string | null;
+    };
+    readonly attributes: JsonValue;
+    readonly instanceDefaults: JsonValue;
+}
+
+declare interface CatalogScope {
+    readonly tenantId: string;
+    readonly channel: string;
+    readonly locale: string;
+}
+
+declare interface CatalogSnapshot {
+    readonly revision: string;
+    readonly items: readonly CatalogItem[];
+}
+
+/** Read only. Call at join/workflow boundaries, never from a room tick. */
+declare interface CatalogSourceService {
+    readonly read: (scope: CatalogScope) => Effect.Effect<CatalogSnapshot, InventoryError>;
+}
+
+declare interface CraftEconomyParticipant {
+    readonly prepareTransfer: (subject: Subject, input: {
+        readonly tenantId: string;
+        readonly requestId: string;
+        readonly currency: string;
+        readonly amount: string;
+        readonly from: {
+            readonly kind: 'wallet';
+            readonly ownerKind: 'player' | 'guild';
+            readonly ownerId: string;
+        };
+        readonly to: {
+            readonly kind: 'system';
+            readonly id: string;
+        };
+        readonly reason: string;
+        readonly ref: {
+            readonly kind: string;
+            readonly id: string;
+        };
+    }) => Effect.Effect<PreparedSqlMutation<CraftPaymentReceipt>, {
+        readonly code: string;
+    }>;
+}
+
+declare interface CraftingOptions {
+    readonly recipes: readonly (RecipeDefinition | Recipe)[];
+    readonly craftResolver?: CraftResolver | undefined;
+    readonly version?: string | undefined;
+    readonly service?: CraftingService | undefined;
+    readonly economy?: CraftEconomyParticipant | undefined;
+    readonly systemAccount?: string | undefined;
+}
+
+/** Small independent seam; InventoryPort retains its eight-method surface. */
+declare interface CraftingService {
+    readonly craft: (subject: Subject, input: CraftRequest) => Effect.Effect<InventoryReceipt, InventoryError>;
+    readonly recipes: (subject: Subject) => Effect.Effect<readonly Recipe[], InventoryError>;
+    readonly exportSubject: (target: PluginPrivacyTarget) => Effect.Effect<unknown, InventoryError>;
+    readonly eraseSubject: (target: PluginPrivacyTarget) => Effect.Effect<void, InventoryError>;
+}
+
+declare interface CraftInput {
+    readonly recipe: Recipe;
+    readonly batches: number;
+    readonly at: number;
+    readonly available: readonly InventoryInstance[];
+    readonly excludedIds: readonly string[];
+}
+
+declare interface CraftPaymentReceipt {
+    readonly txId: string;
+    readonly currency: string;
+    readonly amount: string;
+    readonly at: number;
+}
+
+declare interface CraftPlan {
+    readonly consume: readonly {
+        readonly instanceId: string;
+        readonly qty: number;
+    }[];
+    readonly outputs: readonly RecipeOutput[];
+}
+
+declare interface CraftRequest {
+    readonly tenantId: string;
+    readonly owner: InventoryOwner;
+    readonly recipeId: string;
+    readonly requestId: string;
+    readonly batches?: number;
+}
+
+declare type CraftResolver = (input: CraftInput) => CraftPlan;
+
+/** SQL source owns immutable snapshots and a tenant-wide identity/version registry. */
+export declare const dataStoreCatalog: (store: DataStore, input: SqlCatalogOptions) => Readonly<{
+    read: (scope: CatalogScope) => Effect.Effect<CatalogSnapshot, InventoryError>;
+    importSnapshot: (subject: Subject, input: CatalogImport) => Effect.Effect<CatalogSnapshot, InventoryError>;
+}>;
+
+/** Borrow the app's SQL store. All mutations serialize on a durable owner fence. */
+export declare const dataStoreInventory: (store: DataStore, input: InventoryStoreOptions) => InventorySqlService;
+
+declare interface ExpiryInput {
+    readonly item: CatalogItem;
+    readonly acquiredAt: number;
+}
+
+declare type ExpiryPolicy = (input: ExpiryInput) => number | null;
+
+export declare interface InventoryAudit {
+    readonly instances: number;
+    readonly ledgerRows: number;
+    readonly matches: boolean;
+}
+
+export declare const inventoryCatalogHeadsTable: Table<"_voltro_inv_catalog_heads", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly channel: ColumnBuilder<string, "text", boolean>;
+    readonly locale: ColumnBuilder<string, "text", boolean>;
+    readonly revision: ColumnBuilder<string, "text", boolean>;
+    readonly updatedAt: ColumnBuilder<Date, "timestamp", boolean>;
+}>, true, never>;
+
+export declare const inventoryCatalogLocksTable: Table<"_voltro_inv_catalog_locks", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly admission: ColumnBuilder<number, "integer", boolean>;
+}>, true, never>;
+
+export declare const inventoryCatalogRevisionsTable: Table<"_voltro_inv_catalog_revisions", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly revision: ColumnBuilder<string, "text", boolean>;
+    readonly channel: ColumnBuilder<string, "text", boolean>;
+    readonly locale: ColumnBuilder<string, "text", boolean>;
+    readonly digest: ColumnBuilder<string, "text", boolean>;
+    readonly itemCount: ColumnBuilder<number, "integer", boolean>;
+    readonly createdAt: ColumnBuilder<Date, "timestamp", boolean>;
+}>, true, "voltro_inv_catalog_revisions_scope_idx">;
+
+export declare const inventoryCatalogTable: Table<"_voltro_inv_catalog", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly revision: ColumnBuilder<string, "text", boolean>;
+    readonly channel: ColumnBuilder<string, "text", boolean>;
+    readonly locale: ColumnBuilder<string, "text", boolean>;
+    readonly itemId: ColumnBuilder<string, "text", boolean>;
+    readonly definition: ColumnBuilder<unknown, "json", boolean>;
+}>, true, never>;
+
+export declare const inventoryCatalogTables: readonly [ Table<"_voltro_inv_catalog_locks", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly admission: ColumnBuilder<number, "integer", boolean>;
+}>, true, never>, Table<"_voltro_inv_catalog_heads", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly channel: ColumnBuilder<string, "text", boolean>;
+    readonly locale: ColumnBuilder<string, "text", boolean>;
+    readonly revision: ColumnBuilder<string, "text", boolean>;
+    readonly updatedAt: ColumnBuilder<Date, "timestamp", boolean>;
+}>, true, never>, Table<"_voltro_inv_catalog", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly revision: ColumnBuilder<string, "text", boolean>;
+    readonly channel: ColumnBuilder<string, "text", boolean>;
+    readonly locale: ColumnBuilder<string, "text", boolean>;
+    readonly itemId: ColumnBuilder<string, "text", boolean>;
+    readonly definition: ColumnBuilder<unknown, "json", boolean>;
+}>, true, never>, Table<"_voltro_inv_catalog_versions", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly itemId: ColumnBuilder<string, "text", boolean>;
+    readonly schemaVersion: ColumnBuilder<number, "integer", boolean>;
+    readonly kind: ColumnBuilder<string, "text", boolean>;
+    readonly definition: ColumnBuilder<unknown, "json", boolean>;
+}>, true, never>, Table<"_voltro_inv_catalog_revisions", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly revision: ColumnBuilder<string, "text", boolean>;
+    readonly channel: ColumnBuilder<string, "text", boolean>;
+    readonly locale: ColumnBuilder<string, "text", boolean>;
+    readonly digest: ColumnBuilder<string, "text", boolean>;
+    readonly itemCount: ColumnBuilder<number, "integer", boolean>;
+    readonly createdAt: ColumnBuilder<Date, "timestamp", boolean>;
+}>, true, "voltro_inv_catalog_revisions_scope_idx">];
+
+export declare const inventoryCatalogVersionsTable: Table<"_voltro_inv_catalog_versions", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly itemId: ColumnBuilder<string, "text", boolean>;
+    readonly schemaVersion: ColumnBuilder<number, "integer", boolean>;
+    readonly kind: ColumnBuilder<string, "text", boolean>;
+    readonly definition: ColumnBuilder<unknown, "json", boolean>;
+}>, true, never>;
+
+declare interface InventoryConsume {
+    readonly tenantId: string;
+    readonly owner: InventoryOwner;
+    readonly requestId: string;
+    readonly instanceId: string;
+    readonly qty: number;
+    readonly reason: string;
+    readonly ref: InventoryRef;
+}
+
+declare interface InventoryEquip {
+    readonly slotSet: string;
+    readonly slot: string;
+    readonly instanceId: string | null;
+    readonly requestId: string;
+}
+
+/** Public errors carry codes, never subjects, catalog values or provider causes. */
+declare class InventoryError extends InventoryError_base {
+}
+
+declare const InventoryError_base: Schema.Class<InventoryError, Schema.TaggedStruct<"InventoryError", {
+    readonly code: Schema.Literals<readonly ["invalid_input", "invalid_record", "invalid_item", "invalid_attributes", "conflict", "forbidden", "not_found", "unavailable", "limit_exceeded", "erased", "insufficient_items", "insufficient_funds", "payment_refused", "locked", "expired", "invalid_slot"]>;
+}>, YieldableError>;
+
+declare interface InventoryExpire {
+    readonly tenantId: string;
+    readonly owner: InventoryOwner;
+    readonly requestId: string;
+    readonly until: number;
+}
+
+declare interface InventoryGrant {
+    readonly tenantId: string;
+    readonly owner: InventoryOwner;
+    readonly requestId: string;
+    readonly itemId: string;
+    readonly qty: number;
+    readonly attributes?: JsonValue;
+    readonly reason: string;
+    readonly ref: InventoryRef;
+}
+
+declare interface InventoryInstance {
+    readonly id: string;
+    readonly itemId: string;
+    readonly schemaVersion: number;
+    readonly qty: number;
+    readonly attributes: JsonValue;
+    readonly acquiredAt: number;
+    readonly expiresAt: number | null;
+    readonly locked: boolean;
+    readonly source: string;
+}
+
+export declare const inventoryItemsTable: Table<"_voltro_inv_items", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly ownerKind: ColumnBuilder<"player" | "guild", "text", boolean>;
+    readonly ownerId: ColumnBuilder<string, "text", boolean>;
+    readonly itemId: ColumnBuilder<string, "text", boolean>;
+    readonly schemaVersion: ColumnBuilder<number, "integer", boolean>;
+    readonly qty: ColumnBuilder<number, "integer", boolean>;
+    readonly attributes: ColumnBuilder<unknown, "json", boolean>;
+    readonly acquiredAt: ColumnBuilder<Date, "timestamp", boolean>;
+    readonly expiresAt: ColumnBuilder<Date | null, "timestamp", boolean>;
+    readonly locked: ColumnBuilder<boolean, "boolean", boolean>;
+    readonly source: ColumnBuilder<string, "text", boolean>;
+}>, true, never>;
+
+export declare const inventoryLedgerTable: Table<"_voltro_inv_ledger", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly operationId: ColumnBuilder<string, "text", boolean>;
+    readonly ownerKind: ColumnBuilder<"player" | "guild" | null, "text", boolean>;
+    readonly sequence: ColumnBuilder<number, "integer", boolean>;
+    readonly ownerId: ColumnBuilder<string | null, "text", boolean>;
+    readonly instanceId: ColumnBuilder<string | null, "text", boolean>;
+    readonly itemId: ColumnBuilder<string, "text", boolean>;
+    readonly delta: ColumnBuilder<number, "integer", boolean>;
+    readonly reason: ColumnBuilder<string, "text", boolean>;
+    readonly after: ColumnBuilder<unknown, "json", boolean>;
+    readonly refKind: ColumnBuilder<string | null, "text", boolean>;
+    readonly refId: ColumnBuilder<string | null, "text", boolean>;
+    readonly actor: ColumnBuilder<string | null, "text", boolean>;
+    readonly at: ColumnBuilder<Date, "timestamp", boolean>;
+}>, true, never>;
+
+declare interface InventoryLoadout {
+    readonly slotSet: string;
+    readonly slot: string;
+    readonly instanceId: string;
+}
+
+export declare const inventoryLoadoutsTable: Table<"_voltro_inv_loadouts", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly ownerKind: ColumnBuilder<"player" | "guild", "text", boolean>;
+    readonly ownerId: ColumnBuilder<string, "text", boolean>;
+    readonly slotSet: ColumnBuilder<string, "text", boolean>;
+    readonly slot: ColumnBuilder<string, "text", boolean>;
+    readonly instanceId: ColumnBuilder<string, "text", boolean>;
+}>, true, never>;
+
+export declare const inventoryOperationsTable: Table<"_voltro_inv_operations", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly state: ColumnBuilder<"pending" | "erased" | "committed", "text", boolean>;
+    readonly ownerKey: ColumnBuilder<string | null, "text", boolean>;
+    readonly sequence: ColumnBuilder<number | null, "integer", boolean>;
+    readonly craft: ColumnBuilder<unknown, "json", boolean>;
+    readonly reservation: ColumnBuilder<unknown, "json", boolean>;
+    readonly transfer: ColumnBuilder<unknown, "json", boolean>;
+    readonly digest: ColumnBuilder<string | null, "text", boolean>;
+    readonly receipt: ColumnBuilder<unknown, "json", boolean>;
+    readonly admission: ColumnBuilder<number, "integer", boolean>;
+    readonly createdAt: ColumnBuilder<Date, "timestamp", boolean>;
+}>, true, never>;
+
+export declare const inventoryOwnedTables: readonly [ Table<"_voltro_inv_subjects", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly ownerKind: ColumnBuilder<"player" | "guild", "text", boolean>;
+    readonly ownerId: ColumnBuilder<string | null, "text", boolean>;
+    readonly erased: ColumnBuilder<boolean, "boolean", boolean>;
+    readonly admission: ColumnBuilder<number, "integer", boolean>;
+    readonly sequence: ColumnBuilder<number, "integer", boolean>;
+}>, true, never>, Table<"_voltro_inv_items", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly ownerKind: ColumnBuilder<"player" | "guild", "text", boolean>;
+    readonly ownerId: ColumnBuilder<string, "text", boolean>;
+    readonly itemId: ColumnBuilder<string, "text", boolean>;
+    readonly schemaVersion: ColumnBuilder<number, "integer", boolean>;
+    readonly qty: ColumnBuilder<number, "integer", boolean>;
+    readonly attributes: ColumnBuilder<unknown, "json", boolean>;
+    readonly acquiredAt: ColumnBuilder<Date, "timestamp", boolean>;
+    readonly expiresAt: ColumnBuilder<Date | null, "timestamp", boolean>;
+    readonly locked: ColumnBuilder<boolean, "boolean", boolean>;
+    readonly source: ColumnBuilder<string, "text", boolean>;
+}>, true, never>, Table<"_voltro_inv_loadouts", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly ownerKind: ColumnBuilder<"player" | "guild", "text", boolean>;
+    readonly ownerId: ColumnBuilder<string, "text", boolean>;
+    readonly slotSet: ColumnBuilder<string, "text", boolean>;
+    readonly slot: ColumnBuilder<string, "text", boolean>;
+    readonly instanceId: ColumnBuilder<string, "text", boolean>;
+}>, true, never>, Table<"_voltro_inv_ledger", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly operationId: ColumnBuilder<string, "text", boolean>;
+    readonly ownerKind: ColumnBuilder<"player" | "guild" | null, "text", boolean>;
+    readonly sequence: ColumnBuilder<number, "integer", boolean>;
+    readonly ownerId: ColumnBuilder<string | null, "text", boolean>;
+    readonly instanceId: ColumnBuilder<string | null, "text", boolean>;
+    readonly itemId: ColumnBuilder<string, "text", boolean>;
+    readonly delta: ColumnBuilder<number, "integer", boolean>;
+    readonly reason: ColumnBuilder<string, "text", boolean>;
+    readonly after: ColumnBuilder<unknown, "json", boolean>;
+    readonly refKind: ColumnBuilder<string | null, "text", boolean>;
+    readonly refId: ColumnBuilder<string | null, "text", boolean>;
+    readonly actor: ColumnBuilder<string | null, "text", boolean>;
+    readonly at: ColumnBuilder<Date, "timestamp", boolean>;
+}>, true, never>, Table<"_voltro_inv_operations", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly state: ColumnBuilder<"pending" | "erased" | "committed", "text", boolean>;
+    readonly ownerKey: ColumnBuilder<string | null, "text", boolean>;
+    readonly sequence: ColumnBuilder<number | null, "integer", boolean>;
+    readonly craft: ColumnBuilder<unknown, "json", boolean>;
+    readonly reservation: ColumnBuilder<unknown, "json", boolean>;
+    readonly transfer: ColumnBuilder<unknown, "json", boolean>;
+    readonly digest: ColumnBuilder<string | null, "text", boolean>;
+    readonly receipt: ColumnBuilder<unknown, "json", boolean>;
+    readonly admission: ColumnBuilder<number, "integer", boolean>;
+    readonly createdAt: ColumnBuilder<Date, "timestamp", boolean>;
+}>, true, never>];
+
+declare interface InventoryOwner {
+    readonly ownerKind: 'player' | 'guild';
+    readonly ownerId: string;
+}
+
+declare interface InventoryReceipt {
+    readonly operationId: string;
+    readonly kind: 'grant' | 'consume' | 'equip' | 'expire' | 'craft' | 'reserve' | 'release' | 'transfer-out' | 'transfer-in';
+    readonly changes: readonly {
+        readonly instanceId: string;
+        readonly delta: number;
+    }[];
+    readonly at: number;
+}
+
+export declare const inventoryRecipesTable: Table<"_voltro_inv_recipes", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly recipeId: ColumnBuilder<string, "text", boolean>;
+    readonly version: ColumnBuilder<number, "integer", boolean>;
+    readonly definition: ColumnBuilder<unknown, "json", boolean>;
+    readonly rulesVersion: ColumnBuilder<string, "text", boolean>;
+}>, true, never>;
+
+export declare const inventoryRecipeTables: readonly [ Table<"_voltro_inv_recipes", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly recipeId: ColumnBuilder<string, "text", boolean>;
+    readonly version: ColumnBuilder<number, "integer", boolean>;
+    readonly definition: ColumnBuilder<unknown, "json", boolean>;
+    readonly rulesVersion: ColumnBuilder<string, "text", boolean>;
+}>, true, never>];
+
+declare interface InventoryRef {
+    readonly kind: string;
+    readonly id: string;
+}
+
+export declare interface InventoryReleaseInput {
+    readonly tenantId: string;
+    readonly owner: InventoryOwner;
+    readonly reservationId: string;
+}
+
+/** Original custody proof, separate from current availability. A redacted peer
+ * has no serialized receipt; its retained movement conservation is still checked. */
+export declare interface InventoryReservationEvidence {
+    readonly reservationId: string;
+    readonly state: InventoryReservationView['state'];
+    readonly items: InventoryReservationView['items'];
+    readonly reserve: InventoryReceipt | null;
+    readonly release: InventoryReceipt | null;
+    readonly transfer: {
+        readonly from: InventoryReceipt;
+        readonly to: InventoryReceipt | null;
+    } | null;
+}
+
+export declare interface InventoryReservationTransferInput {
+    readonly tenantId: string;
+    readonly from: InventoryOwner;
+    readonly to: InventoryOwner;
+    readonly reservationId: string;
+}
+
+export declare interface InventoryReservationTransferReceipt {
+    readonly reservationId: string;
+    readonly from: InventoryReceipt;
+    readonly to: InventoryReceipt;
+}
+
+export declare interface InventoryReservationView {
+    readonly reservationId: string;
+    readonly state: 'not-observed' | 'reserved' | 'released' | 'transferred';
+    readonly items: readonly {
+        readonly qty: number;
+        readonly instance: InventoryInstance;
+    }[];
+}
+
+export declare interface InventoryReservedTransferReceipt {
+    readonly reserve: InventoryReceipt;
+    readonly transfer: InventoryReservationTransferReceipt;
+}
+
+/** Trusted server participant input. Selecting quantities never proves ownership. */
+export declare interface InventoryReserveInput {
+    readonly tenantId: string;
+    readonly owner: InventoryOwner;
+    readonly reservationId: string;
+    readonly items: readonly {
+        readonly instanceId: string;
+        readonly qty: number;
+    }[];
+}
+
+export declare interface InventoryReserveTransferInput extends InventoryReservationTransferInput {
+    readonly items: readonly {
+        readonly instanceId: string;
+        readonly qty: number;
+    }[];
+}
+
+/** Installed routes and trusted callers use this same replaceable service. */
+declare interface InventoryService {
+    readonly grant: (subject: Subject, input: InventoryGrant) => Effect.Effect<InventoryReceipt, InventoryError>;
+    readonly consume: (subject: Subject, input: InventoryConsume) => Effect.Effect<InventoryReceipt, InventoryError>;
+    readonly mine: (subject: Subject) => Effect.Effect<readonly InventoryInstance[], InventoryError>;
+    readonly loadout: (subject: Subject, slotSet: string) => Effect.Effect<readonly InventoryLoadout[], InventoryError>;
+    readonly equip: (subject: Subject, input: InventoryEquip) => Effect.Effect<InventoryReceipt, InventoryError>;
+    readonly expire: (subject: Subject, input: InventoryExpire) => Effect.Effect<InventoryReceipt, InventoryError>;
+    readonly exportSubject: (target: PluginPrivacyTarget) => Effect.Effect<unknown, InventoryError>;
+    readonly eraseSubject: (target: PluginPrivacyTarget) => Effect.Effect<void, InventoryError>;
+}
+
+export declare interface InventorySqlService extends InventoryService {
+    readonly prepareConsume: (subject: Subject, input: Parameters<InventoryService['consume']>[1]) => Effect.Effect<PreparedSqlMutation<InventoryReceipt>, InventoryError>;
+    readonly prepareReserveTransfer: (subject: Subject, input: InventoryReserveTransferInput) => Effect.Effect<PreparedSqlMutation<InventoryReservedTransferReceipt>, InventoryError>;
+    readonly prepareReservationTransfer: (subject: Subject, input: InventoryReservationTransferInput) => Effect.Effect<PreparedSqlMutation<InventoryReservationTransferReceipt>, InventoryError>;
+    readonly prepareReserve: (subject: Subject, input: InventoryReserveInput) => Effect.Effect<PreparedSqlMutation<InventoryReceipt>, InventoryError>;
+    readonly prepareRelease: (subject: Subject, input: InventoryReleaseInput) => Effect.Effect<PreparedSqlMutation<InventoryReceipt>, InventoryError>;
+    readonly reservation: (subject: Subject, input: InventoryReleaseInput) => Effect.Effect<InventoryReservationView, InventoryError>;
+    readonly reservationEvidence: (subject: Subject, input: InventoryReleaseInput) => Effect.Effect<InventoryReservationEvidence, InventoryError>;
+    readonly prepareGrant: (subject: Subject, input: InventoryGrant) => Effect.Effect<PreparedSqlMutation<InventoryReceipt>, InventoryError>;
+    readonly prepareCraft: (subject: Subject, input: CraftRequest) => Effect.Effect<PreparedSqlMutation<InventoryReceipt>, InventoryError>;
+    readonly craft: (subject: Subject, input: CraftRequest) => Effect.Effect<InventoryReceipt, InventoryError>;
+    readonly auditInventory: (subject: Subject, tenantId: string, owner: InventoryOwner) => Effect.Effect<InventoryAudit, InventoryError>;
+    readonly rebuildInventory: (subject: Subject, tenantId: string, owner: InventoryOwner) => Effect.Effect<InventoryAudit, InventoryError>;
+}
+
+export declare interface InventoryStoreOptions {
+    readonly items: readonly ItemDefinition[];
+    readonly catalogSource: CatalogSourceService;
+    readonly channel: string;
+    readonly locale: string;
+    readonly allowedServices?: readonly string[] | undefined;
+    readonly slotSets?: Readonly<Record<string, readonly string[]>> | undefined;
+    readonly maxInstances?: number | undefined;
+    readonly maxLedgerRows?: number | undefined;
+    readonly now?: (() => number) | undefined;
+    readonly stackPolicy?: StackPolicy | undefined;
+    readonly expiryPolicy?: ExpiryPolicy | undefined;
+    readonly crafting?: CraftingOptions | undefined;
+}
+
+export declare const inventorySubjectsTable: Table<"_voltro_inv_subjects", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly ownerKind: ColumnBuilder<"player" | "guild", "text", boolean>;
+    readonly ownerId: ColumnBuilder<string | null, "text", boolean>;
+    readonly erased: ColumnBuilder<boolean, "boolean", boolean>;
+    readonly admission: ColumnBuilder<number, "integer", boolean>;
+    readonly sequence: ColumnBuilder<number, "integer", boolean>;
+}>, true, never>;
+
+export declare const inventoryTables: readonly [ Table<"_voltro_inv_catalog_locks", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly admission: ColumnBuilder<number, "integer", boolean>;
+}>, true, never>, Table<"_voltro_inv_catalog_heads", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly channel: ColumnBuilder<string, "text", boolean>;
+    readonly locale: ColumnBuilder<string, "text", boolean>;
+    readonly revision: ColumnBuilder<string, "text", boolean>;
+    readonly updatedAt: ColumnBuilder<Date, "timestamp", boolean>;
+}>, true, never>, Table<"_voltro_inv_catalog", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly revision: ColumnBuilder<string, "text", boolean>;
+    readonly channel: ColumnBuilder<string, "text", boolean>;
+    readonly locale: ColumnBuilder<string, "text", boolean>;
+    readonly itemId: ColumnBuilder<string, "text", boolean>;
+    readonly definition: ColumnBuilder<unknown, "json", boolean>;
+}>, true, never>, Table<"_voltro_inv_catalog_versions", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly itemId: ColumnBuilder<string, "text", boolean>;
+    readonly schemaVersion: ColumnBuilder<number, "integer", boolean>;
+    readonly kind: ColumnBuilder<string, "text", boolean>;
+    readonly definition: ColumnBuilder<unknown, "json", boolean>;
+}>, true, never>, Table<"_voltro_inv_catalog_revisions", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly revision: ColumnBuilder<string, "text", boolean>;
+    readonly channel: ColumnBuilder<string, "text", boolean>;
+    readonly locale: ColumnBuilder<string, "text", boolean>;
+    readonly digest: ColumnBuilder<string, "text", boolean>;
+    readonly itemCount: ColumnBuilder<number, "integer", boolean>;
+    readonly createdAt: ColumnBuilder<Date, "timestamp", boolean>;
+}>, true, "voltro_inv_catalog_revisions_scope_idx">, Table<"_voltro_inv_subjects", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly ownerKind: ColumnBuilder<"player" | "guild", "text", boolean>;
+    readonly ownerId: ColumnBuilder<string | null, "text", boolean>;
+    readonly erased: ColumnBuilder<boolean, "boolean", boolean>;
+    readonly admission: ColumnBuilder<number, "integer", boolean>;
+    readonly sequence: ColumnBuilder<number, "integer", boolean>;
+}>, true, never>, Table<"_voltro_inv_items", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly ownerKind: ColumnBuilder<"player" | "guild", "text", boolean>;
+    readonly ownerId: ColumnBuilder<string, "text", boolean>;
+    readonly itemId: ColumnBuilder<string, "text", boolean>;
+    readonly schemaVersion: ColumnBuilder<number, "integer", boolean>;
+    readonly qty: ColumnBuilder<number, "integer", boolean>;
+    readonly attributes: ColumnBuilder<unknown, "json", boolean>;
+    readonly acquiredAt: ColumnBuilder<Date, "timestamp", boolean>;
+    readonly expiresAt: ColumnBuilder<Date | null, "timestamp", boolean>;
+    readonly locked: ColumnBuilder<boolean, "boolean", boolean>;
+    readonly source: ColumnBuilder<string, "text", boolean>;
+}>, true, never>, Table<"_voltro_inv_loadouts", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly ownerKind: ColumnBuilder<"player" | "guild", "text", boolean>;
+    readonly ownerId: ColumnBuilder<string, "text", boolean>;
+    readonly slotSet: ColumnBuilder<string, "text", boolean>;
+    readonly slot: ColumnBuilder<string, "text", boolean>;
+    readonly instanceId: ColumnBuilder<string, "text", boolean>;
+}>, true, never>, Table<"_voltro_inv_ledger", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly operationId: ColumnBuilder<string, "text", boolean>;
+    readonly ownerKind: ColumnBuilder<"player" | "guild" | null, "text", boolean>;
+    readonly sequence: ColumnBuilder<number, "integer", boolean>;
+    readonly ownerId: ColumnBuilder<string | null, "text", boolean>;
+    readonly instanceId: ColumnBuilder<string | null, "text", boolean>;
+    readonly itemId: ColumnBuilder<string, "text", boolean>;
+    readonly delta: ColumnBuilder<number, "integer", boolean>;
+    readonly reason: ColumnBuilder<string, "text", boolean>;
+    readonly after: ColumnBuilder<unknown, "json", boolean>;
+    readonly refKind: ColumnBuilder<string | null, "text", boolean>;
+    readonly refId: ColumnBuilder<string | null, "text", boolean>;
+    readonly actor: ColumnBuilder<string | null, "text", boolean>;
+    readonly at: ColumnBuilder<Date, "timestamp", boolean>;
+}>, true, never>, Table<"_voltro_inv_operations", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly state: ColumnBuilder<"pending" | "erased" | "committed", "text", boolean>;
+    readonly ownerKey: ColumnBuilder<string | null, "text", boolean>;
+    readonly sequence: ColumnBuilder<number | null, "integer", boolean>;
+    readonly craft: ColumnBuilder<unknown, "json", boolean>;
+    readonly reservation: ColumnBuilder<unknown, "json", boolean>;
+    readonly transfer: ColumnBuilder<unknown, "json", boolean>;
+    readonly digest: ColumnBuilder<string | null, "text", boolean>;
+    readonly receipt: ColumnBuilder<unknown, "json", boolean>;
+    readonly admission: ColumnBuilder<number, "integer", boolean>;
+    readonly createdAt: ColumnBuilder<Date, "timestamp", boolean>;
+}>, true, never>, Table<"_voltro_inv_recipes", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly recipeId: ColumnBuilder<string, "text", boolean>;
+    readonly version: ColumnBuilder<number, "integer", boolean>;
+    readonly definition: ColumnBuilder<unknown, "json", boolean>;
+    readonly rulesVersion: ColumnBuilder<string, "text", boolean>;
+}>, true, never>];
+
+declare const ITEM_KINDS: readonly ["consumable", "equipment", "cosmetic", "currencyBundle", "key", "mod"];
+
+declare interface ItemContract extends Omit<ItemDefinition, 'schemaVersion' | 'equipSlot' | 'expiresAfter' | 'display'> {
+    readonly schemaVersion: number;
+    readonly equipSlot: string | null;
+    readonly expiresAfter: number | null;
+    readonly display: {
+        readonly nameKey: string;
+        readonly icon: string | null;
+    };
+}
+
+declare interface ItemDefinition {
+    readonly id: string;
+    readonly kind: ItemKind;
+    readonly schemaVersion?: number;
+    readonly stackable: boolean;
+    readonly maxStack: number;
+    readonly tradable: boolean;
+    readonly rarity: string;
+    readonly tags: readonly string[];
+    readonly attributes: Schema.Top;
+    readonly instanceAttributes: Schema.Top;
+    readonly equipSlot?: string | null;
+    /** Milliseconds; resolved on grant, never by a tick. */
+    readonly expiresAfter?: number | null;
+    readonly display: {
+        readonly nameKey: string;
+        readonly icon?: string | null;
+    };
+}
+
+declare type ItemKind = typeof ITEM_KINDS[number];
+
+declare type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+
+declare interface Recipe {
+    readonly id: string;
+    readonly version: number;
+    readonly inputs: readonly RecipeIngredient[];
+    readonly outputs: readonly RecipeOutput[];
+    readonly maxBatches: number;
+    readonly cost: RecipeCurrencyCost | null;
+    readonly timeMs: 0;
+    readonly requires: null;
+}
+
+declare interface RecipeCurrencyCost {
+    readonly currency: string;
+    readonly amount: string;
+}
+
+declare interface RecipeDefinition {
+    readonly id: string;
+    readonly version?: number;
+    readonly inputs: readonly RecipeIngredient[];
+    readonly outputs: readonly RecipeOutput[];
+    readonly maxBatches?: number;
+    readonly cost?: RecipeCurrencyCost | null;
+    readonly timeMs?: 0;
+    readonly requires?: null;
+}
+
+declare interface RecipeIngredient {
+    readonly itemId: string;
+    readonly qty: number;
+}
+
+declare interface RecipeOutput extends RecipeIngredient {
+    readonly attributes?: JsonValue;
+}
+
+export declare const resolveInventoryOptions: (input: InventoryStoreOptions) => Readonly<{
+    items: readonly ItemContract[];
+    catalogSource: Readonly<{
+        read: (scope: CatalogScope) => Effect.Effect< CatalogSnapshot, InventoryError>;
+    }>;
+    channel: string;
+    locale: string;
+    slotSets: Readonly<Record<string, readonly string[]>>;
+    allowedServices: readonly string[];
+    maxInstances: number;
+    maxLedgerRows: number;
+    crafting: Readonly<{
+        economy: Readonly<{
+            prepareTransfer: (subject: Subject, input: {
+                readonly tenantId: string;
+                readonly requestId: string;
+                readonly currency: string;
+                readonly amount: string;
+                readonly from: {
+                    readonly kind: "wallet";
+                    readonly ownerKind: "player" | "guild";
+                    readonly ownerId: string;
+                };
+                readonly to: {
+                    readonly kind: "system";
+                    readonly id: string;
+                };
+                readonly reason: string;
+                readonly ref: {
+                    readonly kind: string;
+                    readonly id: string;
+                };
+            }) => Effect.Effect<PreparedSqlMutation< CraftPaymentReceipt>, {
+                readonly code: string;
+            }>;
+        }> | undefined;
+        systemAccount: string | undefined;
+        recipes: readonly Recipe[];
+        craftResolver: CraftResolver;
+        version: string;
+        service: CraftingService | undefined;
+    }> | undefined;
+    now: () => number;
+    stackPolicy: StackPolicy;
+    expiryPolicy: ExpiryPolicy;
+}>;
+
+export declare interface SqlCatalogOptions {
+    readonly items: readonly ItemDefinition[];
+    readonly allowedServices?: readonly string[];
+    readonly maxCatalogItems?: number;
+    readonly maxCatalogVersions?: number;
+    readonly now?: () => number;
+}
+
+declare interface StackInput {
+    readonly item: CatalogItem;
+    readonly quantity: number;
+    readonly available: readonly {
+        readonly id: string;
+        readonly quantity: number;
+    }[];
+}
+
+declare interface StackPlan {
+    readonly existing: readonly {
+        readonly id: string;
+        readonly add: number;
+    }[];
+    readonly create: readonly number[];
+}
+
+declare type StackPolicy = (input: StackInput) => StackPlan;
+
+export { }