state

type CFunction func(L *LuaState) int

type CallInfo struct {
	Func int       // stack index of function slot
	Top  int       // stack index of top for this call
	Prev *CallInfo // caller's CallInfo
	Next *CallInfo // callee's CallInfo (allocated lazily)

	// Lua function fields (valid when CallStatus & CISTC == 0)
	SavedPC    int  // index into Proto.Code (next instruction)
	Trap       bool // tracing active (hooks)
	NExtraArgs int  // extra vararg arguments

	// C function fields (valid when CallStatus & CISTC != 0)
	K          KFunction // continuation for yields
	OldErrFunc int       // saved error function stack index
	Ctx        int       // continuation context

	// Ephemeral union (reused for different purposes)
	NYield  int // number of values yielded
	NRes    int // number of values returned
	FuncIdx int // saved function index for pcall recovery (mirrors ci->u2.funcidx)

	CallStatus uint32 // CIST_* flags
}

type GlobalState struct {
	Registry object.TValue // the registry table
	Seed     uint32        // randomized hash seed

	// I1 FIX: Concrete types where no circular dependency exists
	TMNames [25]*object.LuaString // metamethod name strings
	MT      [9]any                // metatables for basic types (9 = NumTypes, any to avoid Table import cycle)

	MainThread *LuaState         // the main thread
	Panic      CFunction         // unprotected error handler
	MemErrMsg  *object.LuaString // pre-allocated "not enough memory" string

	// String interning table (typed in luastring module)
	StringTable any

	// API string cache (typed in luastring module)
	StringCache any

	// MemoryLimit is the maximum number of bytes Lua objects may use.
	// 0 means no limit. When GCTotalBytes exceeds this after a full GC,
	// further allocations panic with StatusErrMem ("not enough memory").
	MemoryLimit int64

	// GCTotalBytes tracks total Lua-level object allocations (bytes).
	// Mirrors C Lua's gettotalbytes(g) for collectgarbage("count").
	// Incremented on allocation, decremented by V5 GC sweep when dead
	// objects are removed from allgc. Single-threaded access only.
	GCTotalBytes int64

	// GCAllocCount counts table allocations since the last GC cycle.
	// Used to trigger periodic GC during tight allocation loops.
	GCAllocCount int64

	// GCCountdown is a countdown counter for periodic GC triggering.
	// Starts at 5000, decrements each checkGC call. When ≤ 0, triggers GC
	// and resets. Uses countdown instead of modulo for lower inline cost.
	GCCountdown int64

	// GCStepFn is set by the API layer to run a full GC cycle.
	// The VM calls this periodically during allocation-heavy loops.
	// Signature: func(L *LuaState) — runs GCCollect.
	GCStepFn func(L *LuaState)

	// GCDrainFn is set by the API layer to run a lightweight GC cycle.
	// Signature: func(L *LuaState) — runs GCCollect.
	GCDrainFn func(L *LuaState)

	// SweepStringFn is called by GC sweep when a dead short string is found.
	// It removes the string from the string interning table.
	// Set by the API layer to avoid circular imports (gc → luastring).
	SweepStringFn func(obj object.GCObject)

	// GCClosed is set true when the state is closing — suppresses further GC.
	GCClosed bool
	// GCStopped is set true by collectgarbage("stop") — suppresses periodic GC.
	GCStopped bool
	// GCRunning is true while a GC cycle is executing — prevents re-entrant GC.
	// Mirrors C Lua's g->gcrunning flag.
	GCRunning bool
	// GCRunningFinalizer is true while __gc finalizers are being called.
	// Prevents reentrant finalization (mirrors C Lua's GCSTPGC flag in gcstp).
	GCRunningFinalizer bool
	// GCExplicit is true when GC is triggered by explicit collectgarbage() call.
	// When true, traverseThread uses th.Top (precise — dead registers not marked).
	// When false (periodic GC), traverseThread uses maxTop (conservative).
	GCExplicit bool

	// GCMode tracks the current GC mode: "incremental" (default) or "generational".
	// Mirrors C Lua's g->gckind (KGC_INC / KGC_GEN).
	GCMode string

	// GCParams stores GC tuning parameters (pause, stepmul, stepsize, etc.).
	// Go's GC doesn't use these, but we store them so Lua code that
	// reads/writes them (e.g., gc.lua tests) works correctly.
	// Keys: "pause", "stepmul", "stepsize", "minormul", "majorminor", "minormajor"
	GCParams map[string]int64

	// Object chains
	Allgc   object.GCObject // head of all collectable objects
	FinObj  object.GCObject // objects with __gc (separated at setmetatable time)
	TobeFnz object.GCObject // objects whose __gc should run this cycle
	FixedGC object.GCObject // permanent objects (never collected)

	// GC phase
	GCState      byte // current phase (GCSpause, GCSpropagate, etc.)
	CurrentWhite byte // current white bit (flips each cycle)

	// Gray lists (slice-based for cache locality; replaces intrusive GCList)
	Gray      []object.GCObject // objects to be traversed (stack: pop from end)
	GrayAgain []object.GCObject // barrier-back objects (re-traverse in atomic)
	Weak      []object.GCObject // weak-value tables to clear after mark
	AllWeak   []object.GCObject // all-weak (kv) tables
	Ephemeron []object.GCObject // ephemeron tables (weak-key)

	// EphemeronCount tracks how many weak-key (ephemeron) tables were
	// encountered during the current GC mark phase. When zero, the
	// expensive clearDeadKeysAllEphemerons walk can be skipped entirely.
	EphemeronCount int

	// Incremental GC state
	GCDebt     int64            // bytes "owed" — positive = credit, triggers step when <= 0
	GCEstimate int64            // estimate of non-garbage bytes (for setpause)
	SweepGC    *object.GCObject // current position in sweep list (nil = not sweeping)

	// GC tuning parameters (used by debt-based pacing)
	GCPause    int // pause% (default 200 = collect when memory reaches 2x live)
	GCStepMul  int // step multiplier (default 200)
	GCStepSize int // log2 of step size in bytes (default 13 = 8KB)

	// Generational GC state
	GCKind byte // KGC_INC=0, KGC_GENMINOR=1, KGC_GENMAJOR=2

	// Generation list boundary pointers within allgc chain.
	// The allgc chain is ordered: [new objects] → Survival → Old1 → ReallyOld → nil
	// These pointers mark the boundaries between generations.
	Survival  object.GCObject // first survival-age object in allgc
	Old1      object.GCObject // first old1-age object in allgc
	ReallyOld object.GCObject // first really-old object in allgc
	FirstOld1 object.GCObject // optimization: first OLD1 in list

	// Same boundaries for finobj chain
	FinObjSur  object.GCObject // survival boundary in finobj
	FinObjOld1 object.GCObject // old1 boundary in finobj
	FinObjROld object.GCObject // really-old boundary in finobj

	// GCMinorMul is the generational minor collection multiplier.
	// Controls when minor GC switches to major (% of live memory growth).
	GCMinorMul int // default 25 (LUAI_GENMINORMUL)

	// WarnF is the warning handler function. Called with (message, tocont).
	// tocont=true means the message is a continuation (more parts follow).
	// When nil, warnings are silently discarded.
	WarnF func(ud any, message string, tocont bool)

	// WarnUd is the user data passed to WarnF (mirrors C Lua's ud_warn).
	WarnUd any

	// WarnBuf accumulates multi-part warning messages (tocont=true parts).
	WarnBuf string
}

type KFunction func(L *LuaState, status int, ctx int) int

type LuaBaseLevel struct {
	Status int // status from resetthread (usually StatusOK)
}

type LuaError struct {
	Status  int           // error code (StatusErrRun, etc.)
	Message object.TValue // error object (usually a string)
}

type LuaState struct {
	object.GCHeader // GC metadata
	// C3 FIX: Stack uses []StackValue (not []TValue) for TBC support.
	// Each slot has a TBCDelta field for the to-be-closed linked list.
	Stack  []object.StackValue // the value stack
	Top    int                 // index of first free slot
	CI     *CallInfo           // current call info
	BaseCI CallInfo            // embedded base CallInfo (C host level)

	Global    *GlobalState // shared global state
	OpenUpval any          // head of open upvalue list (typed in closure module)
	TBCList   int          // stack index of top to-be-closed variable (-1 = none)

	Status    int    // thread status (StatusOK, StatusYield, etc.)
	AllowHook bool   // hook enable flag
	NCCalls   uint32 // C call depth (low 16) + non-yieldable count (high 16)
	NCI       int    // number of CallInfo nodes in the list

	ErrFunc int // error handler stack index
	OldPC   int // last traced PC

	// CallInfo slab allocation — reduces GC pressure by allocating
	// CallInfos in batches of ciSlabSize instead of individually.
	CISlab    []CallInfo // slab for CallInfo allocation
	CISlabIdx int        // next free index in slab

	// C10 FIX: Debug hook fields (needed by debug.sethook/gethook)
	Hook          any // debug hook function (typed later)
	BaseHookCount int // base hook count setting
	HookCount     int // current hook countdown
	HookMask      int // which hooks active (call, return, line, count)
	FTransfer     int // hook value transfer: index of first value
	NTransfer     int // hook value transfer: number of values
	HookEvent     int // current hook event (HookCall, HookReturn, etc.)
	HookLine      int // current hook line number (-1 if not a line hook)
	// Saved state for hook yield resume (survives panic/yield)
	HookSavedTop   int // L.Top before hook dispatch
	HookSavedCITop int // ci.Top before hook dispatch

	// APIState caches the public api.State wrapper for this LuaState.
	// This avoids allocating a new &State{Internal: ls} on every C function call.
	// Set once during state creation; type is any to avoid circular import.
	APIState any
}

type LuaYield struct {
	NResults int // number of results to yield
}