package dev.shibasis.reaktor.graph.proposal

// Design specimen only. No runtime implementation or production API is installed.

// region identity
data class GraphId(val value: String)
data class EntityId(val graph: GraphId, val value: String)
data class Digest(val value: String)
data class SchemaRef(val id: String, val version: Int, val digest: Digest)
data class BlobRef(val schema: SchemaRef, val digest: Digest, val byteLength: Long)
data class Revision(val graph: GraphId, val digest: Digest)
data class RevisionSet(val entries: List<Revision>, val digest: Digest)
data class SnapshotRef(val definitions: RevisionSet, val factCut: Digest)
data class ActivationRef(
    val instance: String,
    val epoch: Long,
    val definitions: RevisionSet,
)
data class LocalHandle(val slot: Int, val generation: Int)

enum class EntityKind { Node, Port, Edge }
enum class PortRole { Consumer, Provider }
data class Cardinality(val minimum: Int, val maximum: Int?)
data class ContractRef(val schema: SchemaRef)
data class CapabilityKey<T : Any>(val schema: SchemaRef)
data class CapabilityValue(val entity: EntityId, val value: BlobRef)

data class NodeRecord(val id: EntityId)
data class PortRecord(
    val id: EntityId,
    val owner: EntityId,
    val role: PortRole,
    val contract: ContractRef,
    val cardinality: Cardinality,
)
data class EdgeRecord(
    val id: EntityId,
    val from: EntityId,
    val to: EntityId,
    val relation: SchemaRef,
    val bindingContract: ContractRef?,
)
data class GraphDefinition(
    val revision: Revision,
    val nodes: List<NodeRecord>,
    val ports: List<PortRecord>,
    val edges: List<EdgeRecord>,
    val capabilities: List<CapabilityValue>,
)

interface Graph {
    val snapshot: SnapshotRef
    fun node(id: EntityId): NodeRecord?
    fun port(id: EntityId): PortRecord?
    fun edge(id: EntityId): EdgeRecord?
    fun <T : Any> capability(id: EntityId, key: CapabilityKey<T>): T?
}

interface SnapshotLease : AutoCloseable {
    val graph: Graph
    override fun close()
}

interface GraphStore {
    fun acquire(revisions: RevisionSet): SnapshotLease
    fun validate(patch: GraphPatch): ValidationReport
    fun commit(patch: GraphPatch): CommitResult
}

data class Contract<C : Any>(val ref: ContractRef)
data class Consumer<C : Any>(val id: EntityId, val contract: Contract<C>)
data class Provider<C : Any>(val id: EntityId, val contract: Contract<C>)
data class NodeRef<P>(val id: EntityId, val ports: P)

@DslMarker
annotation class GraphDsl

@GraphDsl
interface NodeBuilder {
    val id: EntityId
    fun <T : Any> capability(key: CapabilityKey<T>, value: T)
    fun <C : Any> consumes(key: String, contract: Contract<C>): Consumer<C>
    fun <C : Any> provides(key: String, contract: Contract<C>): Provider<C>
}

@GraphDsl
interface GraphBuilder {
    fun <P> node(key: String, configure: NodeBuilder.() -> P): NodeRef<P>
    fun <C : Any> connect(
        key: String,
        consumer: Consumer<C>,
        provider: Provider<C>,
        relation: SchemaRef,
    ): EntityId
    fun build(): GraphDefinition
}
// endregion

fun <C : Any> messagingBindings(
    graph: GraphBuilder,
    messaging: Contract<C>,
    bindingRelation: SchemaRef,
): GraphDefinition = with(graph) {
    val chat = node("chat") { consumes("messaging", messaging) }
    val endpoint = node("messaging") { provides("api", messaging) }
    connect("chat.messaging", chat.ports, endpoint.ports, bindingRelation)
    build()
}

// region maps
sealed interface Selection {
    data object All : Selection
    data class Ids(val ids: List<EntityId>) : Selection
    data class HasCapability(val schema: SchemaRef) : Selection
    data class Union(val inputs: List<Selection>) : Selection
    data class Intersection(val inputs: List<Selection>) : Selection
    data class Difference(val left: Selection, val right: Selection) : Selection
}

data class ReadContext(
    val workspace: String,
    val environment: String,
    val principalRef: String,
    val tenantRef: String?,
    val visibilityPolicy: Digest,
    val snapshot: SnapshotRef,
)

data class MapDefinition(
    val id: EntityId,
    val version: Digest,
    val selection: Selection,
    val projectedCapabilities: List<SchemaRef>,
    val derivations: List<ProgramRef>,
)

enum class BoundaryReason { Unloaded, Inaccessible, Unavailable, Unknown }
data class Frontier(val ref: EntityId?, val reason: BoundaryReason)
data class Coverage(
    val completeWithinDeclaredScope: Boolean,
    val frontier: List<Frontier>,
    val staleEvidence: List<Digest>,
)

data class MapResult(
    val definition: MapDefinition,
    val context: ReadContext,
    val graph: Graph,
    val coverage: Coverage,
    val lineage: List<Digest>,
)

interface MapEngine {
    suspend fun evaluate(definition: MapDefinition, context: ReadContext): MapResult
}

enum class Direction { Outgoing, Incoming, Both }
enum class TraversalOrder { BreadthFirst, DepthFirst, Topological, StrongComponents }
data class TraversalBudget(val maxEntities: Int, val maxEdges: Int, val maxDepth: Int)
data class TraversalSpec(
    val starts: List<EntityId>,
    val relations: List<SchemaRef>,
    val direction: Direction,
    val order: TraversalOrder,
    val budget: TraversalBudget,
)

interface Cancellation {
    fun isRequested(): Boolean
}

enum class VisitAction { Continue, Prune, Stop }
data class Visit(val entity: EntityId, val viaEdge: EntityId?, val depth: Int)
data class VisitStep<A>(val accumulator: A, val action: VisitAction)

fun interface Visitor<A> {
    fun visit(graph: Graph, at: Visit, accumulator: A): VisitStep<A>
}

enum class StopReason { Exhausted, VisitorStopped, BudgetExceeded, Cancelled, InvalidStrategy }
data class TraversalResult<A>(
    val value: A,
    val reason: StopReason,
    val coverage: Coverage,
    val visitedEntities: Int,
    val examinedEdges: Int,
)

interface Traversal {
    fun <A> run(
        map: MapResult,
        spec: TraversalSpec,
        initial: A,
        cancellation: Cancellation,
        visitor: Visitor<A>,
    ): TraversalResult<A>
}
// endregion

// region services
data class EffectRequirement(val operation: SchemaRef, val resourceSelector: BlobRef)
enum class Interaction { Unary, Stream, Publish, Subscribe, DurableJob }
data class Operation<C : Any, I : Any, O : Any>(
    val id: String,
    val contract: Contract<C>,
    val input: SchemaRef,
    val output: SchemaRef,
    val errors: SchemaRef,
    val interaction: Interaction,
    val effects: List<EffectRequirement>,
)

data class InvocationContext(
    val operationId: String,
    val activation: ActivationRef,
    val authorityRef: String,
    val remainingBudgetMillis: Long,
    val idempotencyKey: String?,
    val causationRef: String?,
)

enum class EffectOutcome { NotStarted, Applied, PartiallyApplied, Unknown }
data class CallFailure(val code: String, val outcome: EffectOutcome, val evidence: Digest?)
sealed interface CallResult<out T> {
    data class Success<T>(val value: T, val receipt: Digest) : CallResult<T>
    data class Failure(val failure: CallFailure) : CallResult<Nothing>
}

interface BoundService<C : Any> {
    suspend fun <I : Any, O : Any> call(
        operation: Operation<C, I, O>,
        input: I,
        context: InvocationContext,
    ): CallResult<O>
}

interface RuntimeIsland {
    val activation: ActivationRef
    fun <C : Any> bind(consumer: Consumer<C>): BoundService<C>
}

enum class Durability { Volatile, PersistedBeforeAcceptance, TransactionalOutbox }
enum class Routing { FanOut, CompetingConsumers, KeyAffinity }
enum class Ordering { Unordered, PerKey, PerPartition }
enum class Overflow { Wait, Reject, DropOldest, DropNewest }
enum class AckPoint { Accepted, HandlerCompleted, TransactionCommitted }
data class DeliveryPolicy(
    val durability: Durability,
    val routing: Routing,
    val ordering: Ordering,
    val ackPoint: AckPoint,
    val maxInFlight: Int,
    val maxBufferedBytes: Long,
    val overflow: Overflow,
    val retryProfile: BlobRef,
    val deduplicationProfile: BlobRef?,
    val deadLetter: EntityId?,
)
data class ChannelDefinition(val entity: EntityId, val message: SchemaRef)
data class SubscriptionDefinition(
    val entity: EntityId,
    val channel: EntityId,
    val handlerPort: EntityId,
    val filter: ProgramRef?,
    val delivery: DeliveryPolicy,
)
data class PublishReceipt(val messageId: String, val durability: Durability, val evidence: Digest)
interface Publisher<T : Any> {
    suspend fun publish(message: T, context: InvocationContext): CallResult<PublishReceipt>
}
// endregion

// region programs
data class ProgramRef(val digest: Digest, val profile: SchemaRef)
data class Register(val index: Int, val schema: SchemaRef)
data class BlockId(val index: Int)
sealed interface Instruction {
    data class Constant(val target: Register, val value: BlobRef) : Instruction
    data class Compute(
        val target: Register,
        val intrinsic: SchemaRef,
        val arguments: List<Register>,
    ) : Instruction
    data class Invoke(
        val target: Register,
        val operation: SchemaRef,
        val input: Register,
    ) : Instruction
}
sealed interface Terminator {
    data class Branch(val condition: Register, val yes: BlockId, val no: BlockId) : Terminator
    data class Jump(val target: BlockId) : Terminator
    data class Return(val value: Register) : Terminator
}
data class ProgramBlock(val id: BlockId, val instructions: List<Instruction>, val end: Terminator)
data class ProgramDefinition(
    val ref: ProgramRef,
    val entry: BlockId,
    val input: Register,
    val result: SchemaRef,
    val blocks: List<ProgramBlock>,
    val imports: List<SchemaRef>,
    val effects: List<EffectRequirement>,
    val sourceMap: BlobRef,
)
data class ExecutionBudget(val fuel: Long, val memoryBytes: Long, val effectCalls: Int)
// endregion

// region changes
data class EntityPrecondition(val entity: EntityId, val expectedDigest: Digest?)
sealed interface PatchOp {
    data class PutNode(val value: NodeRecord) : PatchOp
    data class PutPort(val value: PortRecord) : PatchOp
    data class PutEdge(val value: EdgeRecord) : PatchOp
    data class PutCapability(val value: CapabilityValue) : PatchOp
    data class RemoveCapability(val entity: EntityId, val schema: SchemaRef) : PatchOp
    data class RemoveEntity(val entity: EntityId) : PatchOp
}
data class GraphPatch(
    val id: String,
    val base: Revision,
    val preconditions: List<EntityPrecondition>,
    val operations: List<PatchOp>,
    val sourceAuthorityRef: String,
)
data class Finding(val rule: String, val subjects: List<EntityId>, val evidence: Digest?)
data class ValidationReport(val patchDigest: Digest, val accepted: Boolean, val findings: List<Finding>)
sealed interface CommitResult {
    data class Committed(val revision: Revision, val receipt: Digest) : CommitResult
    data class Rejected(val report: ValidationReport) : CommitResult
    data class Conflict(val current: Revision) : CommitResult
}
data class CommandRequest(val operation: SchemaRef, val input: BlobRef, val context: ReadContext)
data class PlanRef(val digest: Digest)
data class Plan(
    val ref: PlanRef,
    val inputs: SnapshotRef,
    val patches: List<GraphPatch>,
    val commands: List<CommandRequest>,
    val requiredEffects: List<EffectRequirement>,
    val requiredEvidence: List<EntityId>,
    val expiresAtEpochMillis: Long,
)
data class ExecutionReceipt(val plan: PlanRef, val outcome: EffectOutcome, val evidence: List<Digest>)
interface ChangeProtocol {
    suspend fun prepare(patches: List<GraphPatch>, commands: List<CommandRequest>): Plan
    suspend fun execute(plan: PlanRef, authorityRef: String): ExecutionReceipt
    suspend fun reconcile(plan: PlanRef, authorityRef: String): ExecutionReceipt
}
// endregion

// region evidence
enum class TestKind { Unit, Contract, Property, Integration, Scenario, Performance, Memory, Model }
data class TestDefinition(
    val entity: EntityId,
    val kind: TestKind,
    val subject: Selection,
    val program: ProgramRef,
    val fixture: BlobRef,
    val requiredEffects: List<EffectRequirement>,
    val acceptance: BlobRef,
)
enum class Assurance { Observed, Tested, BoundedChecked, ProvenUnderAssumptions }
data class EvidenceRecord(
    val test: EntityId,
    val testRevision: Digest,
    val runId: String,
    val inputs: SnapshotRef,
    val artifacts: List<Digest>,
    val targetProfile: BlobRef,
    val seed: Long?,
    val assumptions: BlobRef,
    val assurance: Assurance,
    val result: BlobRef,
)
interface GraphVerifier {
    fun selectTests(patch: GraphPatch, graph: Graph): List<EntityId>
    suspend fun verify(plan: PlanRef, authorityRef: String): List<EvidenceRecord>
}
// endregion

// region integration
data class CapabilityDescriptor(
    val schema: SchemaRef,
    val validOn: Set<EntityKind>,
    val requires: List<SchemaRef>,
    val excludes: List<SchemaRef>,
    val requiredBehavior: SchemaRef?,
)
enum class HookPurpose { Transform, Enforce, Observe }
data class HookDescriptor(
    val id: SchemaRef,
    val boundary: SchemaRef,
    val input: SchemaRef,
    val output: SchemaRef,
    val purpose: HookPurpose,
    val handler: SchemaRef,
    val before: List<SchemaRef>,
    val after: List<SchemaRef>,
    val effects: List<EffectRequirement>,
    val budget: ExecutionBudget,
    val failurePolicy: SchemaRef,
)
data class QueryDependency(
    val entities: Selection,
    val readsSchemas: List<SchemaRef>,
)
data class ProjectionDescriptor(
    val id: EntityId,
    val sourceContract: SchemaRef,
    val outputSchemas: List<SchemaRef>,
    val dependencies: List<QueryDependency>,
    val effects: List<EffectRequirement>,
    val retentionProfile: SchemaRef,
)
data class InspectorDescriptor(
    val id: SchemaRef,
    val subjects: Selection,
    val maps: List<EntityId>,
    val actions: List<SchemaRef>,
    val rendererContract: SchemaRef,
)
data class GraphIntegrationManifest(
    val module: SchemaRef,
    val requiresModules: List<SchemaRef>,
    val capabilities: List<CapabilityDescriptor>,
    val contracts: List<ContractRef>,
    val projections: List<ProjectionDescriptor>,
    val maps: List<MapDefinition>,
    val operations: List<SchemaRef>,
    val hooks: List<HookDescriptor>,
    val inspectors: List<InspectorDescriptor>,
    val conformanceTests: List<EntityId>,
)
data class ProjectionCursor(val source: EntityId, val generation: String, val position: String)
data class ProjectionBudget(val maxEntities: Int, val maxBytes: Long, val remainingMillis: Long)
data class ProjectionRequest(
    val projection: EntityId,
    val context: ReadContext,
    val authorityRef: String,
    val after: ProjectionCursor?,
    val budget: ProjectionBudget,
)
enum class SourceAvailability { Available, Unavailable, Unsupported, Unknown }
data class ProjectionPage(
    val source: EntityId,
    val sourceRevision: Digest?,
    val records: BlobRef,
    val next: ProjectionCursor?,
    val resetRequired: Boolean,
    val availability: SourceAvailability,
    val coverage: Coverage,
)
interface GraphProjectionSource {
    suspend fun read(request: ProjectionRequest): ProjectionPage
}
interface InstalledGraphIntegration : AutoCloseable {
    val manifest: GraphIntegrationManifest
    fun source(id: EntityId): GraphProjectionSource?
    override fun close()
}
data class SemanticFocus(
    val entity: EntityId,
    val map: EntityId?,
    val activation: ActivationRef?,
    val evidence: Digest?,
)
data class FlowStep(
    val id: String,
    val focus: SemanticFocus,
    val viaEdge: EntityId?,
    val causedBy: List<String>,
)
data class FlowSelection(val id: String, val steps: List<FlowStep>, val lineage: List<Digest>)
data class WorkbenchContext(
    val read: ReadContext,
    val maps: List<EntityId>,
    val focus: SemanticFocus?,
    val flow: FlowSelection?,
    val missionId: String?,
    val runId: String?,
)
// endregion