# phpef-runtime-native-standard TODO

## Compare native standard wrappers against runtime-embed

Every native `phpfunc_*` wrapper added here must receive explicit comparison
coverage against the existing `phpef-runtime-embed` behavior before it is treated
as semantically interchangeable.

For each native `phpfunc_*` wrapper:

- first list the corresponding declarations from `phpef-runtime-embed.vapi` and implement every matching public variant in the native package with the exact same wrapper name/signature, including the base Zval wrapper and all typed/derived wrappers;
- compare native vs embed output/return values;
- cover every supported argument variant;
- cover return variants and PHP/Zval coercion edge cases;
- document intentionally native-only typed fast paths separately;
- keep the native implementation compatible with embed PHP semantics unless a
  deliberate divergence is documented.

Standing rule for future NativeStandard additions:

- every new public native `phpfunc_*` wrapper must add at least one native-vs-embed comparison test with representative example calls before it is treated as a drop-in replacement;
- do not rely on native-only smoke tests for semantic parity;
- if exact equality is impossible because the function is time/random/environment dependent, compare shape, type, range, and bounded delta against Embed and document why.

Done:

- `phpfunc_microtime()` has native-vs-embed coverage in
  `tests/microtime_embed_compare.vala` for no argument, `false`, `null`, `0`,
  `'0'`, `true`, `1`, and `'1'`; the native-only
  `phpfunc_microtime_typed_double_arg1_bool_true()` helper is checked against embed
  `microtime(true)` for time proximity.
- `phpfunc_floatval()`, `phpfunc_floor()`, `phpfunc_round()`, and
  `phpfunc_number_format()` have native-vs-embed example coverage in
  `tests/standard_math_embed_compare.vala`.
- `phpfunc_constant()` has native-vs-embed example coverage in
  `tests/standard_constant_embed_compare.vala` for Core and standard constants,
  including generated-table values such as `PHP_EOL`, `DIRECTORY_SEPARATOR`,
  `PATH_SEPARATOR`, `INF`, and `NAN`. The typed string-argument wrapper
  `phpfunc_constant_typed_zval_arg1_string(string name): Zval` is covered
  against Embed for representative mixed-return constants.

## Generated native `phpfunc_constant()` tables

`phpfunc_constant()` in `phpef-runtime-native-standard` is generated at build time by `tools/generate_standard_constants.vala`. The generator calls `PhpefRuntimeEmbed.phpfunc_get_defined_constants(true)`, extracts the `Core` and `standard` categories, and writes build-local `standard_constant_helpers.vala`. The source tree must not contain an ad-hoc hand-written constant list.

Current integration rules:

- the generator depends on `phpef-runtime-embed` and intentionally uses sibling pre-devel build VAPIs so stale installed packages do not hide new metadata helpers;
- `Core` and `standard` must both exist and be non-empty; otherwise generation fails instead of silently producing an incomplete native runtime;
- generated constant tables still expose the same public `phpfunc_constant(Zval name)` wrapper shape as Embed so `library-embed2native` can switch calls without changing ABI;
- future `phpef-runtime-native-*` packages must generate from their own `get_defined_constants(true)` category, not copy the standard/Core categories;
- when multiple native runtime packages provide `phpfunc_constant()`, the optimizer needs an explicit composition/nesting strategy instead of blindly choosing one provider. This is an optimizer TODO: route by known constant ownership/category where possible and define deterministic fallback ordering when more than one native runtime is available.

## Native `file_get_contents()` support for embedded PHPEF resources

Future native-standard coverage must include the Embed call shape produced for embedded resources:

```vala
PhpefRuntimeEmbed.phpfunc_file_get_contents(Zval.from_string("phpef-resource:///assets/hello.txt"))
```

This needs call resolution before it can become a native fast path:

- resolve `phpef-resource:///...` arguments through the PHPEF embedded-resource mapping rather than treating them as ordinary runtime strings;
- once resolved, generated binaries should not need the literal `phpef-resource:///assets/hello.txt` string anymore;
- use the resource mapping/index id from the embedded-resource index instead, so the native path can load the resource by deterministic index/section metadata;
- add native-vs-embed comparison coverage for this path before considering `phpfunc_file_get_contents()` semantically interchangeable with Embed.
