Compatibility first • Oracle execution layer • native JINX runner

JINX is the PHP/Zend compatibility project we pushed toward Oracle-backed execution.

This site explains the JINX work: capturing PHP/Zend behavior, mirroring it through Oracle records, proving output parity with PHP, exercising the native ./jinx executable, expanding generated callable coverage, benchmarking traversal, and keeping PASM/native output as the later emission target.

Run the commands Oracle command docs Native vs PHP benchmark doc Island rundown

Overview

JINX is being shaped as a PHP-compatible execution and compilation project. The contract is not “almost PHP.” The contract is PHP/Zend behavior: PHP source goes in, behavior is recorded and mirrored by Oracle, and every executable family must be proven against real PHP output, return values, and errors before it can be claimed.

1PHP sourceFixtures, scripts, includes, functions, language constructs, and builtins.

2Oracle recordsJINX captures program shape into Oracle-level operation records.

3Oracle executionNarrow families run through dedicated runtime owners.

4PHP parity testsBehavior is compared against PHP, not guessed.

5Native/PASM laterNative output follows once Oracle owns behavior.

The core direction is correctness-first: Oracle is the interpreter and mirroring layer; PASM/native binary output is a later target and should not block PHP/Zend coverage.

Architecture

PHP/Zend compatibility contract

JINX treats PHP and Zend behavior as the source of truth. Output, return behavior, warnings, errors, include paths, and builtins have to match PHP before a feature is considered executable.

Oracle as the execution layer

Oracle is the place where PHP program structure becomes records and executable families. It is the bridge between PHP behavior and future native targets.

PASM/native as later output

PASM and native binary generation are downstream. They become safer once Oracle has modeled the semantics instead of skipping directly to machine output.

PHP / Zend behavior
  → JINX parser and recorder
  → Oracle operation records
  → Oracle runtime family executor
  → PHP comparison test
  → later PASM / native output

What we did for JINX

The project work was organized around proof, not claims. Each new surface had to add runtime ownership, fixtures, comparison tests, docs, and command coverage.

Area	Work completed or established
Execution families	Created the pattern for adding narrow executable families: dedicated runtime owner class, family registration, fixture, PHP comparison test, test-bin wiring, docs, commit, and push.
Straight-line execution	Established the first narrow Oracle execution family for simple straight-line PHP behavior.
Conditionals direction	Defined the next family direction around `if`/`else`, comparisons, and PHP boolean truthiness.
Includes and requires	Documented literal local `include`, `include_once`, `require`, and `require_once` as Oracle entry points when safely resolvable.
Native executable	Kept the requirement that benchmark and runtime checks use the native `./jinx` executable, not only PHP wrapper scripts.
All-functions callable direction	Set the goal that every PHP function should be callable through the JINX executable, with generated callable coverage and parameterized benchmark traversal.
Docs and commands	Added command documentation, benchmark documentation, island rundown documentation, Oracle command notes, and project direction notes.

Oracle execution

Oracle is not just a notation layer. It is the execution mirror where PHP/Zend program behavior is captured, inspected, and then executed by increasingly broad runtime families.

Runtime owner class

Each executable family gets a dedicated owner so behavior does not become anonymous glue code.

Family registry

Executable families are listed centrally so tests and commands can report what Oracle actually runs.

Fixture

Every feature gets a concrete input program that exercises the behavior.

PHP comparison test

Parity is proven by comparing Oracle behavior against PHP output, return, and error behavior.

1. Add a dedicated runtime owner class.
2. Register the executable family.
3. Add a fixture.
4. Add a PHP comparison test.
5. Wire the test into scripts/test-bin-jinx.php.
6. Update docs and commands.
7. Commit and push.

PHP builtins and generated callables

A major JINX goal is to make PHP callable coverage concrete. Generated wrapper dispatch tables and native command paths let the native executable walk every known callable name and report coverage instead of hand-waving it.

Generated callables Oracle dispatch PHP fallback states Manual-driven implementation states All-functions benchmark traversal

Sensitive or exactness-heavy areas such as crypto, hash, password, and random behavior stay PHP-fallback until exact native implementations exist. That keeps the compatibility contract honest.

Benchmarks

The benchmark work separates native JINX traversal from PHP comparison baselines. The point is to measure how fast JINX can walk and dispatch callable surfaces while still validating correctness against PHP where behavior is benchmarkable.

./jinx scripts/test-jinx-native-suite.php
./jinx scripts/test-bin-jinx.php
./jinx scripts/benchmark-native-vs-php.php

Benchmark claims should name exactly what was measured: native dispatch traversal, Oracle execution family behavior, or PHP comparison runtime. Do not call arbitrary PHP execution complete unless Oracle actually runs that behavior and a PHP comparison test proves parity.

JINX island server

The island/server work models a web application shape in Oracle: route dispatch, resident island state, back-page API bridge, iframe island rendering, EventSource invalidation, and response envelopes.

Route	Purpose
`GET /`	Window index frame / entry page.
`GET /island`	Iframe island render.
`GET /events/island-state`	EventSource invalidation stream.
`GET /api/island-state`	Read resident island state.
`POST /api/island-state`	Update resident island state.
`GET /__health`	Health check route.

./jinx scripts/test-oracle-jinx-island-server-execution.php
./jinx scripts/serve-no-js-islands-demo.php --check
./jinx scripts/test-jinx-native-suite.php

Native `./jinx`

The native executable matters because it is the proof path for Oracle dispatch and future native generation. Commands should run through ./jinx when the goal is native behavior, not through a PHP-only wrapper.

scripts/build-native-jinx.sh
./jinx --help
./jinx oracle-call strlen "hello"
./jinx scripts/test-jinx-native-suite.php

PASM direction

PASM is the lower-level target direction, but it should come after PHP-to-Oracle behavior is reliable. Once Oracle can model the PHP/Zend behavior, the project can safely emit toward PASM or native lower-level forms.

Current priority

PHP/Zend behavior captured and executed through Oracle with proof tests.

Later output

PHP → Oracle → PASM/native output, including lower-level representations suitable for future native acceleration.

Commands

These are practical command families used around the JINX work.

Build native JINX

git pull origin master
scripts/build-native-jinx.sh
./jinx --help

Run native suite

./jinx scripts/test-jinx-native-suite.php

Run Oracle execution tests

./jinx scripts/test-bin-jinx.php
./jinx scripts/test-oracle-jinx-island-server-execution.php

Check the island demo

./jinx scripts/serve-no-js-islands-demo.php --check

Benchmark native vs PHP paths

./jinx scripts/benchmark-native-vs-php.php

Status rules

JINX documentation and commits should keep a strict language standard:

Do not claim PHP execution unless Oracle actually runs that behavior.
Do not claim parity unless a PHP comparison test proves output, return, and error behavior.
Keep PHP/Zend behavior as the compatibility contract.
Keep Oracle as the execution and mirroring layer.
Keep PASM/native output as a later target until Oracle behavior is mature.
Use ./jinx for native checks when the requirement is native execution.

Practical rule: each new family should leave behind code, fixture, comparison proof, command wiring, and documentation.