engine

type DeadlineHost interface {
	// CheckDeadline reports the script having run out of time, or its client
	// having gone away, as the error that ends the run.
	CheckDeadline() error
}

type Entry struct {
	Key   any
	Value any
}

type FrameLocals interface {
	Snapshot() map[string]any
	WriteBack(vars map[string]any)
}

type Host interface {
	Construct(string, []any) (any, error)
	CallMethod(any, string, []any) (any, error)
	Call(string, string, []any) (any, error)
	GetProperty(any, string) any
	SetProperty(any, string, any, string) error
	Lookup(string) any
	// SetGlobal offers a whole-variable store to the host before the frame
	// keeps it. A host claims names with cross-frame semantics — PHP's
	// superglobals — by returning true; the engine then leaves the frame slot
	// cold, so later reads keep resolving through Lookup.
	SetGlobal(string, any) bool
	// Constant resolves a bare name. The error is what an undefined one
	// raises, which Lookup has no way to report.
	Constant(string) (any, error)
	// SetConstant declares a constant, the write side of Constant. A
	// top-level `const` entry goes through it so both spellings of a global
	// constant share one table.
	SetConstant(string, any)
	Array([]model.ArrayItemValue) any
	Index(any, any) any
	SetIndex(any, any, any, bool, string) error
	// SetEntry writes value into container at key when container is a value the
	// script owns. A collection a binding returned belongs to the host, so it is
	// left alone rather than reported as an error, matching what a by-reference
	// foreach over one does in the interpreter.
	SetEntry(container, key, value any) error
	// UnsetIndex removes key from container, PHP's unset($a[$k]). Removing a
	// key that is not there is not an error.
	//
	// It answers the container to store back, or nil when the removal was in
	// place. A native slice cannot hold a hole and cannot shrink through the
	// interface value holding it, so removing from one answers a shorter
	// slice for the caller to assign.
	UnsetIndex(container, key any) (replacement any, err error)
	// MatchCatch reports whether a catch clause declaring declaredType handles
	// err. The class hierarchy, the `A|B` union form and the rule that
	// `catch (Exception)` does not catch an engine error all live in the host,
	// so both backends select the same clause.
	MatchCatch(declaredType string, err error) bool
	// Throw turns a thrown value into the error it travels as. A built-in
	// throwable is an error already; an instance of a declared class is
	// wrapped so a clause can filter on the class it was declared as, and a
	// catch binding it gets the object back.
	Throw(value any) error
	// CatchValue returns what a catch clause binds for err, which is the object
	// for a thrown instance and the error itself for everything else.
	CatchValue(err error) any
	// ClassConst reads the constant name off class. The compiler has already
	// collapsed `self`, `static` and `parent` to the enclosing class, so the
	// name arrives concrete; `Class::class` still reaches the host, since it
	// resolves without the class being declared.
	ClassConst(class, name string) (any, error)
	// Cast applies a PHP type cast, spelled by its bare type name: "bool",
	// "int", "float", "string", "array".
	Cast(typ string, value any) any
	Binary(string, any, any) (any, error)
	Unary(string, any) (any, error)
	Truthy(any) bool
	Entries(any) []Entry
	Echo(any) error
	// InvokeCallable runs a deferred callable value on the host bridge.
	InvokeCallable(any) error
}

type MemoryHost interface {
	// MemoryCheckInterval returns the number of instructions between memory
	// checks; zero disables checking. Live-value registration happens either
	// way, so usage queries still see VM state.
	MemoryCheckInterval() int
	// PushLiveWalker registers an enumerator over every live VM value;
	// PopLiveWalker removes it. Calls nest across nested Run invocations.
	PushLiveWalker(func(yield func(any)))
	PopLiveWalker()
	// CheckMemory reports the limit error, if any.
	CheckMemory() error
}

type Program struct {
	// contains filtered or unexported fields
}