NebulaPhysicalItemMachine

package dev.nebulastorage.api.platform

import dev.nebulastorage.api.production.ProductionCapabilityId
import dev.nebulastorage.api.production.ProductionRecipeId
import dev.nebulastorage.api.resource.ResourceKey
import net.minecraft.core.BlockPos
import net.minecraft.server.level.ServerLevel
import net.minecraft.world.item.ItemStack
import net.minecraft.world.level.block.entity.BlockEntity

fun interface NebulaPhysicalItemMachineAdapter {
    /** Called on the server thread. Resolution must neither load chunks nor mutate resources or configuration. */
    fun resolve(level: ServerLevel, position: BlockPos): NebulaPhysicalItemMachine?
}

/**
 * A certified single-process owner whose inventory, progress and Nebula persistent data share its complete chunk NBT.
 * Reads return detached stacks. Simulation is read-only. Execution returns actual transferred quantities and components.
 * Nebula holds one durable operation lease from delivery through collection; changes by other actors must remain observable.
 * Remote inventories, automatic output redirection and owners with additional persistence require another recovery protocol.
 */
interface NebulaPhysicalItemMachine : NebulaPhysicalMachine {
    override val entity: BlockEntity
    override val capabilities: Set<ProductionCapabilityId>
    override fun configurationProblem(): String?
    fun input(): ItemStack
    fun output(): ItemStack
    fun insertInput(stack: ItemStack, simulate: Boolean): ItemStack
    fun extractOutput(amount: Int, simulate: Boolean): ItemStack
    /** Returns only input still present, including cancellation after processing has started. */
    fun extractInput(amount: Int, simulate: Boolean): ItemStack
    override fun matchesRecipe(id: ProductionRecipeId, inputs: Map<ResourceKey, Long>, outputs: Map<ResourceKey, Long>): Boolean
    override fun status(): PhysicalMachineStatus
}

/**
 * Independent processing lanes persisted in the same complete owner NBT. Lane indices remain stable across reloads.
 * Automatic redistribution between lanes must be disabled while Nebula owns work. Each lane observes only its own inputs and outputs.
 * Every returned port has the same entity and capabilities as this owner; parallelism is between 1 and 64.
 */
interface NebulaParallelPhysicalItemMachine : NebulaPhysicalItemMachine {
    val parallelism: Int
    fun lane(index: Int): NebulaPhysicalItemMachine
}

/** Progress is normalized to the recipe's nominal duration when upgrades change actual processing time. */
data class PhysicalMachineStatus(val ticks: Int, val canProcess: Boolean, val waitingReason: String? = null)