/** Save data for a registry; definitions must be structured-cloneable and use the caller's serialization format. */
export interface ItemInstanceRegistryState<TDef> {
    prefix: string;
    sequence: number;
    entries: [string, TDef][];
}
/** Caller-owned synchronous storage; `entries()` must stream without materializing the collection. */
export interface ItemInstanceStorage<TDef> {
    get(id: string): TDef | undefined;
    has(id: string): boolean;
    set(id: string, def: TDef): void;
    delete(id: string): void;
    count(): number;
    entries(): Iterable<[string, TDef]>;
    /** Consume entries completely and atomically replace storage; any failure must preserve previous data. */
    replace(entries: Iterable<[string, TDef]>): void;
}
/** Inject storage and its saved allocator sequence when attaching an existing collection. */
export interface ItemInstanceRegistryOptions<TDef> {
    storage?: ItemInstanceStorage<TDef>;
    /** Nonnegative safe integer; defaults to zero. Retain it across releases and storage reattachment. */
    sequence?: number;
}
/**
 * A runtime store for procedurally generated item instances — a rolled unique gun, a rolled
 * affixed relic — keyed by a generated id distinct from any static catalog id. The counterpart a
 * game's `content.itemById` consults for ids `lootTable`'s `generate` entries hand back, so runtime
 * rolls never need a hand-rolled parallel registry (#536.1).
 */
export interface ItemInstanceRegistry<TDef> {
    /** Detached definitions and allocator state, including ids of released instances in the sequence. */
    state(): ItemInstanceRegistryState<TDef>;
    /** Detached batches of at most `pageSize` entries; throws if the registry changes during iteration. Keep external storage and definitions unchanged until finished. */
    statePages(pageSize: number): IterableIterator<ItemInstanceRegistryState<TDef>>;
    /** Replace the registry; returns false without mutation when the prefix or allocator is invalid. */
    restore(next: ItemInstanceRegistryState<TDef>): boolean;
    /** Stream detached pages through atomic storage replacement. All pages must share prefix and sequence; malformed pages or storage failures throw without changing state. Empty saves require one empty page. */
    restorePages(pages: Iterable<ItemInstanceRegistryState<TDef>>): boolean;
    /** Stores `def` under a fresh generated id derived from `baseId`; returns that id. */
    register(baseId: string, def: TDef): string;
    get(id: string): TDef | undefined;
    has(id: string): boolean;
    /** Drop a generated instance once nothing references it (consumed, destroyed, sold). */
    release(id: string): void;
    count(): number;
}
/**
 * Builds an {@link ItemInstanceRegistry}; generated ids are `"<prefix>:<baseId>:<n>"`, unique per
 * registry instance.
 *
 * @capability item-instance-registry a runtime store for procedurally generated item instances
 */
export declare function createItemInstanceRegistry<TDef>(prefix?: string, options?: ItemInstanceRegistryOptions<TDef>): ItemInstanceRegistry<TDef>;
/**
 * Bridges any procedural roller into a `LootEntry.generate` callback: rolls a `{ baseId, def }` pair
 * and registers it, returning the runtime id the loot roll hands back as the drop's `item`.
 *
 * @capability item-instance-registry roll and register a procedural item as a loot-table drop
 */
export declare function proceduralLootEntry<TDef>(registry: ItemInstanceRegistry<TDef>, roll: (rng: () => number) => {
    baseId: string;
    def: TDef;
}): (rng: () => number) => string;