Problem
AGENTS.md defines the off-limits surface for packages built on z-engine as "every method marked @internal and anything handing out a raw FFI\CData/FFI\CType". The marking is applied inconsistently:
Marked @internal: HashTable::getRawValue(), ReflectionClass::getRawValue(), ObjectEntry::getPropertyTablePointer() / getDynamicPropertiesPointer().
Not marked (but hand out raw CData/pointers):
StringEntry::getRawValue() (src/Type/StringEntry.php:185)
ObjectEntry::getRawValue() (src/Type/ObjectEntry.php:325)
ReflectionValue::getRawValue() (src/Reflection/ReflectionValue.php:562)
ReflectionClassConstant::getRawValue() (src/Reflection/ReflectionClassConstant.php:119)
ClosureEntry::getRawFunction() (src/Type/ClosureEntry.php:155)
ResourceEntry::getRawData() (src/Type/ResourceEntry.php:123)
OpLine::getHandler() (src/Type/OpLine.php:109)
ReflectionExtension::getGlobals() (src/Reflection/ReflectionExtension.php:117) — fully public, returns bare \FFI\CData, no marker at all
Related naming scatter for the same concept: getRawValue() / getRawData() / getRawFunction() / getEntryPointer() / getPropertyTablePointer().
Proposal
Pick one rule (suggest: every method returning raw CData/CType carries @internal), apply it across src/Type and src/Reflection, and note the naming convention for future accessors in AGENTS.md. Depends on the API-contract decision in the companion README/AGENTS issue only for ReflectionExtension::getGlobals().
Found during the 2026-08 modernization review.
Problem
AGENTS.md defines the off-limits surface for packages built on z-engine as "every method marked
@internaland anything handing out a rawFFI\CData/FFI\CType". The marking is applied inconsistently:Marked
@internal:HashTable::getRawValue(),ReflectionClass::getRawValue(),ObjectEntry::getPropertyTablePointer()/getDynamicPropertiesPointer().Not marked (but hand out raw CData/pointers):
StringEntry::getRawValue()(src/Type/StringEntry.php:185)ObjectEntry::getRawValue()(src/Type/ObjectEntry.php:325)ReflectionValue::getRawValue()(src/Reflection/ReflectionValue.php:562)ReflectionClassConstant::getRawValue()(src/Reflection/ReflectionClassConstant.php:119)ClosureEntry::getRawFunction()(src/Type/ClosureEntry.php:155)ResourceEntry::getRawData()(src/Type/ResourceEntry.php:123)OpLine::getHandler()(src/Type/OpLine.php:109)ReflectionExtension::getGlobals()(src/Reflection/ReflectionExtension.php:117) — fully public, returns bare\FFI\CData, no marker at allRelated naming scatter for the same concept:
getRawValue()/getRawData()/getRawFunction()/getEntryPointer()/getPropertyTablePointer().Proposal
Pick one rule (suggest: every method returning raw
CData/CTypecarries@internal), apply it acrosssrc/Typeandsrc/Reflection, and note the naming convention for future accessors in AGENTS.md. Depends on the API-contract decision in the companion README/AGENTS issue only forReflectionExtension::getGlobals().Found during the 2026-08 modernization review.