@barefootjs/php 0.1.0

package/tests/test_evaluator.php

@@ -0,0 +1,274 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Hand-built ParsedExpr evaluator demonstrations, ported from
+ * packages/adapter-perl/t/evaluator.t (see also the Python port's
+ * test_evaluator.py).
+ *
+ * Mirrors the Go/Perl/Python evaluator test demonstrations so all backends
+ * prove the SAME restriction-lifting on the SAME shapes (a
+ * reducer/comparator/predicate body the fixed bf.reduce/bf.sort/bf.filter
+ * catalogues can't express, but the evaluator handles as just another pure
+ * expression). Nodes are hand-built as plain PHP associative arrays (the
+ * Evaluator tolerates this shape as well as a decoded stdClass -- see
+ * Evaluator.php's docstring).
+ */
+
+require_once __DIR__ . '/_harness.php';
+bf_require_runtime();
+bf_reset();
+
+use Barefoot\Evaluator;
+
+function bft_id(string $name): array
+{
+    return ['kind' => 'identifier', 'name' => $name];
+}
+
+function bft_mem(array $obj, string $prop): array
+{
+    return ['kind' => 'member', 'object' => $obj, 'property' => $prop, 'computed' => false];
+}
+
+function bft_bin(string $op, array $left, array $right): array
+{
+    return ['kind' => 'binary', 'op' => $op, 'left' => $left, 'right' => $right];
+}
+
+function bft_str($value): array
+{
+    return ['kind' => 'literal', 'value' => $value, 'literalType' => 'string'];
+}
+
+function bft_num($value): array
+{
+    return ['kind' => 'literal', 'value' => $value, 'literalType' => 'number'];
+}
+
+function bft_call_math(string $fn, array $arg): array
+{
+    return ['kind' => 'call', 'callee' => bft_mem(bft_id('Math'), $fn), 'args' => [$arg]];
+}
+
+function bft_includes(array $obj, array $needle): array
+{
+    return ['kind' => 'array-method', 'method' => 'includes', 'object' => $obj, 'args' => [$needle]];
+}
+
+function bft_join(array $obj, ?array $sep = null): array
+{
+    return ['kind' => 'array-method', 'method' => 'join', 'object' => $obj, 'args' => $sep === null ? [] : [$sep]];
+}
+
+function bft_arrow(array $params, array $body): array
+{
+    return ['kind' => 'arrow', 'params' => $params, 'body' => $body];
+}
+
+function bft_nested(string $method, array $object, array $arrow): array
+{
+    return [
+        'kind' => 'call',
+        'callee' => ['kind' => 'member', 'object' => $object, 'property' => $method, 'computed' => false],
+        'args' => [$arrow],
+    ];
+}
+
+bf_test('fold: arbitrary reducer body (acc + item.price * item.qty)', function () {
+    $body = bft_bin('+', bft_id('acc'), bft_bin('*', bft_mem(bft_id('item'), 'price'), bft_mem(bft_id('item'), 'qty')));
+    $items = [['price' => 5, 'qty' => 3], ['price' => 2, 'qty' => 4]];
+    bf_assert_eq(Evaluator::fold($items, $body, 'acc', 'item', 0, 'left'), 23.0);
+});
+
+bf_test('fold: direction is observable for string concat', function () {
+    $body = bft_bin('+', bft_id('acc'), bft_id('item'));
+    $items = ['a', 'b', 'c'];
+    bf_assert_eq(Evaluator::fold($items, $body, 'acc', 'item', '', 'left'), 'abc');
+    bf_assert_eq(Evaluator::fold($items, $body, 'acc', 'item', '', 'right'), 'cba');
+});
+
+bf_test('sort_by: arbitrary comparator (abs of field difference)', function () {
+    $cmp = bft_bin('-', bft_call_math('abs', bft_mem(bft_id('a'), 'v')), bft_call_math('abs', bft_mem(bft_id('b'), 'v')));
+    $items = [['v' => -5], ['v' => 3], ['v' => -1]];
+    $sorted = Evaluator::sortBy($items, $cmp, 'a', 'b');
+    bf_assert_eq(array_map(fn ($x) => $x['v'], $sorted), [-1, 3, -5]);
+});
+
+bf_test('sort_by: descending via reversed comparator', function () {
+    $cmp = bft_bin('-', bft_mem(bft_id('b'), 'x'), bft_mem(bft_id('a'), 'x'));
+    $items = [['x' => 10], ['x' => 30], ['x' => 20]];
+    $sorted = Evaluator::sortBy($items, $cmp, 'a', 'b');
+    bf_assert_eq(array_map(fn ($x) => $x['x'], $sorted), [30, 20, 10]);
+});
+
+bf_test('non-finite division and JS stringification', function () {
+    $div = fn ($a, $b) => Evaluator::evaluate(bft_bin('/', bft_id('a'), bft_id('b')), ['a' => $a, 'b' => $b]);
+    bf_assert_eq($div(1, 0), INF);
+    bf_assert_eq($div(-1, 0), -INF);
+    $nan = $div(0, 0);
+    bf_assert(is_float($nan) && is_nan($nan), 'expected NaN for 0/0');
+
+    // _to_string is private; exercise the same paths via `String()` builtin call.
+    $toString = fn ($v) => Evaluator::evaluate(['kind' => 'call', 'callee' => bft_id('String'), 'args' => [bft_num($v)]], []);
+    bf_assert_eq($toString(INF), 'Infinity');
+    bf_assert_eq($toString(-INF), '-Infinity');
+    bf_assert_eq($toString(INF - INF), 'NaN');
+});
+
+bf_test('captured free vars via base_env', function () {
+    $body = bft_bin('+', bft_id('acc'), bft_bin('*', bft_id('item'), bft_id('factor')));
+    $total = Evaluator::fold([1, 2, 3], $body, 'acc', 'item', 0, 'left', ['factor' => 10]);
+    bf_assert_eq($total, 60.0);
+
+    $cmp = bft_bin(
+        '-',
+        bft_call_math('abs', bft_bin('-', bft_id('a'), bft_id('pivot'))),
+        bft_call_math('abs', bft_bin('-', bft_id('b'), bft_id('pivot')))
+    );
+    $sorted = Evaluator::sortBy([1, 8, 4], $cmp, 'a', 'b', ['pivot' => 5]);
+    bf_assert_eq($sorted, [4, 8, 1]);
+});
+
+bf_test('boolean-valued ops return real booleans', function () {
+    $lt = Evaluator::evaluate(bft_bin('<', bft_id('a'), bft_id('b')), ['a' => 1, 'b' => 2]);
+    bf_assert(is_bool($lt), 'expected a real bool from <');
+    bf_assert_eq($lt, true);
+
+    $cat = Evaluator::evaluate(bft_bin('+', bft_str('x'), bft_bin('<', bft_id('a'), bft_id('b'))), ['a' => 1, 'b' => 2]);
+    bf_assert_eq($cat, 'xtrue');
+
+    $eq = Evaluator::evaluate(bft_bin('===', bft_id('a'), bft_id('b')), ['a' => 1, 'b' => 1]);
+    bf_assert(is_bool($eq), 'expected a real bool from ===');
+    bf_assert_eq($eq, true);
+
+    $not = Evaluator::evaluate(['kind' => 'unary', 'op' => '!', 'argument' => bft_str('')], []);
+    bf_assert_eq($not, true);
+
+    $b = Evaluator::evaluate(['kind' => 'call', 'callee' => bft_id('Boolean'), 'args' => [bft_str('')]], []);
+    bf_assert(is_bool($b), 'expected a real bool from Boolean()');
+    bf_assert_eq($b, false);
+
+    // `.length` is a string/array property only; a numeric scalar has none.
+    $length = Evaluator::evaluate(bft_mem(bft_id('n'), 'length'), ['n' => 123]);
+    bf_assert_eq($length, null);
+});
+
+bf_test('array-method .includes dispatches by receiver type', function () {
+    $hit = Evaluator::evaluate(bft_includes(bft_id('tags'), bft_str('go')), ['tags' => ['perl', 'go']]);
+    bf_assert(is_bool($hit) && $hit === true, 'expected true for a matching tag');
+
+    $miss = Evaluator::evaluate(bft_includes(bft_id('tags'), bft_str('rust')), ['tags' => ['perl', 'go']]);
+    bf_assert(is_bool($miss) && $miss === false, 'expected false for a missing tag');
+
+    // SameValueZero, not loose equality: numeric 2 matches numeric needle 2,
+    // but the string needle "2" (a different JS type) does not.
+    $numHit = Evaluator::evaluate(bft_includes(bft_id('nums'), bft_num(2)), ['nums' => [1, 2, 3]]);
+    bf_assert_eq($numHit, true);
+    $numVsString = Evaluator::evaluate(bft_includes(bft_id('nums'), bft_str('2')), ['nums' => [1, 2, 3]]);
+    bf_assert_eq($numVsString, false);
+
+    $sub = Evaluator::evaluate(bft_includes(bft_id('name'), bft_str('ar')), ['name' => 'bare']);
+    bf_assert_eq($sub, true);
+
+    // A non-array, non-string receiver (number, null, object) is not a JS
+    // `.includes` target; the evaluator degrades to false rather than raising.
+    $scalarRecv = Evaluator::evaluate(bft_includes(bft_id('n'), bft_num(1)), ['n' => 42]);
+    bf_assert_eq($scalarRecv, false);
+});
+
+bf_test('strictEq: int/float unify numerically', function () {
+    bf_assert_eq(Evaluator::strictEq(1, 1.0), true);
+    bf_assert_eq(Evaluator::strictEq(1, 2), false);
+    bf_assert_eq(Evaluator::strictEq('1', 1), false, 'no string<->number coercion');
+    bf_assert_eq(Evaluator::strictEq(null, null), true);
+    bf_assert_eq(Evaluator::strictEq(null, false), false);
+    bf_assert_eq(Evaluator::strictEq(NAN, NAN), false, 'NaN !== NaN');
+});
+
+bf_test('sameValueZero: NaN matches NaN, otherwise same as strictEq', function () {
+    bf_assert_eq(Evaluator::sameValueZero(NAN, NAN), true);
+    bf_assert_eq(Evaluator::sameValueZero(1, 1.0), true);
+    bf_assert_eq(Evaluator::sameValueZero('2', 2), false);
+});
+
+bf_test('array-method .join: default separator, custom separator, null element', function () {
+    $default = Evaluator::evaluate(bft_join(bft_id('a')), ['a' => [1, 2, 3]]);
+    bf_assert_eq($default, '1,2,3');
+
+    $custom = Evaluator::evaluate(bft_join(bft_id('a'), bft_str(' - ')), ['a' => ['x', 'y']]);
+    bf_assert_eq($custom, 'x - y');
+
+    // A null element joins as '', not the string "null".
+    $withNull = Evaluator::evaluate(bft_join(bft_id('a'), bft_str(',')), ['a' => ['x', null, 'z']]);
+    bf_assert_eq($withNull, 'x,,z');
+
+    $empty = Evaluator::evaluate(bft_join(bft_id('a')), ['a' => []]);
+    bf_assert_eq($empty, '');
+});
+
+bf_test('nested .map: string-prefix projection inside a callback body', function () {
+    $body = bft_bin('+', bft_str('#'), bft_id('t'));
+    $node = bft_nested('map', bft_id('tags'), bft_arrow(['t'], $body));
+    $out = Evaluator::evaluate($node, ['tags' => ['go', 'php']]);
+    bf_assert_eq($out, ['#go', '#php']);
+});
+
+bf_test('nested .map: 2-param arrow (value, index)', function () {
+    $body = bft_bin('+', bft_id('t'), bft_id('i'));
+    $node = bft_nested('map', bft_id('xs'), bft_arrow(['t', 'i'], $body));
+    $out = Evaluator::evaluate($node, ['xs' => [10, 20, 30]]);
+    bf_assert_eq($out, [10.0, 21.0, 32.0]);
+});
+
+bf_test('nested .filter: predicate over the callback param', function () {
+    $body = bft_bin('>', bft_id('n'), bft_num(1));
+    $node = bft_nested('filter', bft_id('xs'), bft_arrow(['n'], $body));
+    $out = Evaluator::evaluate($node, ['xs' => [1, 2, 3]]);
+    bf_assert_eq($out, [2, 3]);
+});
+
+bf_test('nested .map/.filter: child scope does not leak into the parent env', function () {
+    // If the callback's env were shared (not copied), binding "t" inside the
+    // nested call would corrupt an outer "t" in the parent scope.
+    $body = bft_bin('+', bft_str('#'), bft_id('t'));
+    $node = bft_nested('map', bft_id('tags'), bft_arrow(['t'], $body));
+    $env = ['tags' => ['a', 'b'], 't' => 'OUTER'];
+    $out = Evaluator::evaluate($node, $env);
+    bf_assert_eq($out, ['#a', '#b']);
+    bf_assert_eq($env['t'], 'OUTER', 'outer env must be untouched after the nested call');
+});
+
+bf_test('.length works on both arrays and strings (code points, not bytes)', function () {
+    $arrLen = Evaluator::evaluate(bft_mem(bft_id('xs'), 'length'), ['xs' => [1, 2, 3]]);
+    bf_assert_eq($arrLen, 3);
+
+    $strLen = Evaluator::evaluate(bft_mem(bft_id('s'), 'length'), ['s' => 'abc']);
+    bf_assert_eq($strLen, 3);
+
+    // Multi-byte UTF-8 string: 3 code points, more than 3 bytes.
+    $utf8Len = Evaluator::evaluate(bft_mem(bft_id('s'), 'length'), ['s' => 'héllo']);
+    bf_assert_eq($utf8Len, 5);
+});
+
+bf_test('nested .filter composed with .length', function () {
+    $pred = bft_bin('>', bft_id('n'), bft_num(1));
+    $filtered = bft_nested('filter', bft_id('xs'), bft_arrow(['n'], $pred));
+    $lengthGtZero = bft_bin('>', bft_mem($filtered, 'length'), bft_num(0));
+    $out = Evaluator::evaluate($lengthGtZero, ['xs' => [1, 2, 3]]);
+    bf_assert_eq($out, true);
+
+    $outEmpty = Evaluator::evaluate($lengthGtZero, ['xs' => [1]]);
+    bf_assert_eq($outEmpty, false);
+});
+
+bf_test('formatNumber: shortest round-trip, JS integral spelling', function () {
+    bf_assert_eq(Evaluator::formatNumber(1.0), '1');
+    bf_assert_eq(Evaluator::formatNumber(0.1), '0.1');
+    bf_assert_eq(Evaluator::formatNumber(0.30000000000000004), '0.30000000000000004');
+    bf_assert_eq(Evaluator::formatNumber(0.0), '0');
+    bf_assert_eq(Evaluator::formatNumber(-0.0), '0');
+});
+
+return bf_finish();

package/tests/test_helper_vectors.php

@@ -0,0 +1,334 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Golden helper-vector conformance, ported from
+ * packages/adapter-perl/t/helper_vectors.t (see also the Python port's
+ * test_helper_vectors.py).
+ *
+ * Runs packages/adapter-tests/vectors/vectors.json -- generated from
+ * the JS reference implementations (spec/template-helpers.md) -- against
+ * this package's BarefootJS runtime. One binding per canonical helper id in
+ * the spec catalogue, bound to the exact code shape a compiled Twig
+ * template would execute (a `bf.<method>(...)` call, or the native PHP
+ * operator the adapter emits for add/sub/mul/div/neg).
+ *
+ * Per spec/template-helpers.md's "Adapter status model", this backend's
+ * divergences from the JS-normative expect live in
+ * `tests/vector-divergences.json` (package-local, next to this file) --
+ * keyed by fn/note, mirroring the Perl/Python harnesses' divergence tables
+ * (values differ where PHP's actual behaviour differs from Perl's/Python's,
+ * all independently re-derived and verified against a live PHP 8.4
+ * interpreter -- see the runtime source docstrings). This harness fails on
+ * stale or dead declarations in that file; it's checked again, centrally,
+ * by packages/adapter-tests/src/__tests__/divergences.test.ts.
+ *
+ * Unlike the Python/Perl/Ruby ports, a missing golden-vector corpus or a
+ * missing vector-divergences.json is a LOUD failure here, not a silent
+ * skip -- a silent skip after the corpus moved from
+ * packages/adapter-tests/helper-vectors/ to packages/adapter-tests/vectors/
+ * (#2084) let the suite quietly shrink from ~387 cases to 64 with zero
+ * reported failures.
+ */
+
+require_once __DIR__ . '/_harness.php';
+bf_require_runtime();
+bf_reset();
+
+use Barefoot\BarefootJS;
+use Barefoot\Evaluator;
+
+$VECTORS_PATH = __DIR__ . '/../../adapter-tests/vectors/vectors.json';
+$DIVERGENCES_PATH = __DIR__ . '/vector-divergences.json';
+
+if (!is_file($VECTORS_PATH)) {
+    bf_test('golden vectors corpus is present', function () use ($VECTORS_PATH) {
+        bf_assert(false, "vectors.json not found at {$VECTORS_PATH} -- regenerate it (cd packages/adapter-tests && bun run generate:helper-vectors) or check this path after a corpus move");
+    });
+    return bf_finish();
+}
+
+if (!is_file($DIVERGENCES_PATH)) {
+    bf_test('vector-divergences.json is present', function () use ($DIVERGENCES_PATH) {
+        bf_assert(false, "vector-divergences.json not found at {$DIVERGENCES_PATH} -- this backend's divergence declarations are required, see packages/adapter-tests/vectors/README.md");
+    });
+    return bf_finish();
+}
+
+$backend = new class {
+    public function encode_json($data): string
+    {
+        return \Barefoot\Json::canonicalEncode($data);
+    }
+
+    public function mark_raw($s)
+    {
+        return $s;
+    }
+
+    public function materialize($value)
+    {
+        return is_callable($value) ? $value() : $value;
+    }
+
+    public function render_named(...$args)
+    {
+        return '';
+    }
+};
+
+$bf = new BarefootJS(null, ['backend' => $backend]);
+
+// -----------------------------------------------------------------
+// Predicate builders for the projection-form vector cases (spec: items +
+// field [+ value]) -- rebuilds the predicate closure the adapter compiles.
+// -----------------------------------------------------------------
+
+function bfv_truthy_pred(BarefootJS $bf, string $field): callable
+{
+    return function ($item) use ($bf, $field) {
+        if (!is_array($item) && !($item instanceof \stdClass)) {
+            return false;
+        }
+        $v = $item instanceof \stdClass ? ($item->$field ?? null) : ($item[$field] ?? null);
+        return $bf->truthy($v);
+    };
+}
+
+function bfv_field_eq_pred(string $field, $value): callable
+{
+    return function ($item) use ($field, $value) {
+        if (!is_array($item) && !($item instanceof \stdClass)) {
+            return false;
+        }
+        $v = $item instanceof \stdClass ? ($item->$field ?? null) : ($item[$field] ?? null);
+        return Evaluator::strictEq($v, $value);
+    };
+}
+
+function bfv_bind_sort(BarefootJS $bf, $recv, ...$spec)
+{
+    $keys = [];
+    while (count($spec) >= 4) {
+        [$kind, $name, $compareType, $direction] = array_splice($spec, 0, 4);
+        $keys[] = ['key_kind' => $kind, 'key' => $name, 'compare_type' => $compareType, 'direction' => $direction];
+    }
+    return $bf->sort($recv, ['keys' => $keys]);
+}
+
+function bfv_bind_reduce(BarefootJS $bf, $recv, $op, $keyKind, $key, $rtype, $init, $direction)
+{
+    $seed = $rtype === 'numeric' ? (float) $init : $init;
+    return $bf->reduce($recv, [
+        'op' => $op, 'key_kind' => $keyKind, 'key' => $key, 'type' => $rtype, 'init' => $seed, 'direction' => $direction,
+    ]);
+}
+
+/**
+ * Dispatch one vector case's `fn` to the exact runtime call shape a
+ * compiled template would emit. Throws for helper ids with no PHP binding
+ * (fail loudly rather than silently skip) and lets underlying runtime
+ * exceptions (e.g. DivisionByZeroError) propagate to the caller.
+ */
+function bfv_call(BarefootJS $bf, string $fn, array $args)
+{
+    switch ($fn) {
+        case 'add': return $args[0] + $args[1];
+        case 'sub': return $args[0] - $args[1];
+        case 'mul': return $args[0] * $args[1];
+        case 'div': return $args[0] / $args[1];
+        case 'mod': return $bf->mod($args[0], $args[1]);
+        case 'neg': return -$args[0];
+        case 'string': return $bf->string($args[0]);
+        case 'json': return $bf->json($args[0]);
+        case 'number': return $bf->number($args[0]);
+        case 'floor': return $bf->floor($args[0]);
+        case 'ceil': return $bf->ceil($args[0]);
+        case 'round': return $bf->round($args[0]);
+        case 'to_fixed': return $bf->to_fixed(...$args);
+        case 'lower': return $bf->lc($args[0]);
+        case 'upper': return $bf->uc($args[0]);
+        case 'trim': return $bf->trim($args[0]);
+        case 'starts_with': return $bf->starts_with(...$args);
+        case 'ends_with': return $bf->ends_with(...$args);
+        case 'replace': return $bf->replace(...$args);
+        case 'repeat': return $bf->repeat(...$args);
+        case 'pad_start': return $bf->pad_start(...$args);
+        case 'pad_end': return $bf->pad_end(...$args);
+        case 'split': return $bf->split(...$args);
+        case 'len': return $bf->length($args[0]);
+        case 'at': return $bf->at(...$args);
+        case 'includes': return $bf->includes(...$args);
+        case 'index_of': return $bf->index_of(...$args);
+        case 'last_index_of': return $bf->last_index_of(...$args);
+        case 'concat': return $bf->concat($args[0], $args[1]);
+        case 'slice': return $bf->slice($args[0], $args[1], $args[2] ?? null);
+        case 'reverse': return $bf->reverse($args[0]);
+        case 'flat': return $bf->flat(...$args);
+        case 'flat_dynamic': return $bf->flat_dynamic(...$args);
+        case 'join': return $bf->join(...$args);
+        case 'arr': return $args; // variadic array-literal elements, in order
+        case 'filter_truthy': return array_values(array_filter($args[0], fn ($x) => $bf->truthy($x)));
+        case 'search_params_get': return BarefootJS::search_params($args[0])->get($args[1]);
+        case 'query': return $bf->query(...$args);
+        case 'every': return $bf->every($args[0], bfv_truthy_pred($bf, $args[1]));
+        case 'some': return $bf->some($args[0], bfv_truthy_pred($bf, $args[1]));
+        case 'filter': return $bf->filter($args[0], bfv_field_eq_pred($args[1], $args[2]));
+        case 'find': return $bf->find($args[0], bfv_field_eq_pred($args[1], $args[2]));
+        case 'find_index': return $bf->find_index($args[0], bfv_field_eq_pred($args[1], $args[2]));
+        case 'find_last': return $bf->find_last($args[0], bfv_field_eq_pred($args[1], $args[2]));
+        case 'find_last_index': return $bf->find_last_index($args[0], bfv_field_eq_pred($args[1], $args[2]));
+        case 'sort': return bfv_bind_sort($bf, ...$args);
+        case 'reduce': return bfv_bind_reduce($bf, ...$args);
+        case 'flat_map': return $bf->flat_map(...$args);
+        case 'flat_map_tuple': return $bf->flat_map_tuple(...$args);
+        default:
+            throw new \RuntimeException("no PHP binding for helper '{$fn}' -- add it to bfv_call()");
+    }
+}
+
+/**
+ * Per-backend status declarations (spec/template-helpers.md "Adapter status
+ * model"), loaded from tests/vector-divergences.json (package-local, next
+ * to this file). Divergence entry forms (JSON schema, see
+ * packages/adapter-tests/vectors/README.md):
+ *   {"expect": <value>}              assert the pinned value (exact --
+ *                                    deliberately stricter than bfv_match's
+ *                                    value-compat so an int-vs-float
+ *                                    rounding accident can't hide behind the
+ *                                    comparison)
+ *   {"expect": {"$num": "NaN"}}      assert a real NaN result
+ *   {"throws": true, "exception": <FQCN>}  assert the call throws that
+ *                                    exception class (defaults to
+ *                                    \Throwable if `exception` is absent)
+ *
+ * Every entry was independently re-derived against a live PHP 8.4
+ * interpreter (see php -r probes referenced in the runtime source
+ * docstrings), not copy-pasted from the Perl/Python tables -- several of
+ * PHP's actual divergent VALUES differ from Perl's even though the REASON
+ * is the same class of divergence (e.g. PHP's `sort` produces the same
+ * ["B","a"] ordering Python does, not Perl's differently-cased fixture).
+ */
+$divergencesDoc = json_decode(file_get_contents($DIVERGENCES_PATH), true);
+$DIVERGENCES = $divergencesDoc['divergences'] ?? [];
+$UNSUPPORTED = $divergencesDoc['unsupported'] ?? [];
+
+function bfv_match($got, $expect): bool
+{
+    if ($expect === null) {
+        return $got === null;
+    }
+    if (is_array($expect) && array_key_exists('$num', $expect) && count($expect) === 1) {
+        $kind = $expect['$num'];
+        if (is_bool($got) || !(is_int($got) || is_float($got))) {
+            return false;
+        }
+        $g = (float) $got;
+        if ($kind === 'NaN') {
+            return is_nan($g);
+        }
+        return $g === ($kind === 'Infinity' ? INF : -INF);
+    }
+    if (is_bool($expect)) {
+        return (bool) $got === $expect;
+    }
+    if (is_array($expect) && array_is_list($expect)) {
+        if (!is_array($got) || !array_is_list($got) || count($got) !== count($expect)) {
+            return false;
+        }
+        foreach ($expect as $i => $e) {
+            if (!bfv_match($got[$i] ?? null, $e)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    if (is_array($expect)) { // JSON object
+        $gotArr = $got instanceof \stdClass ? get_object_vars($got) : (is_array($got) ? $got : null);
+        if ($gotArr === null || count($gotArr) !== count($expect)) {
+            return false;
+        }
+        foreach ($expect as $k => $v) {
+            if (!array_key_exists($k, $gotArr) || !bfv_match($gotArr[$k], $v)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    if ($got === null || is_array($got) || $got instanceof \stdClass) {
+        return false;
+    }
+    if ((is_int($expect) || is_float($expect))) {
+        if (is_bool($got) || !(is_int($got) || is_float($got))) {
+            return false;
+        }
+        if (is_int($got) && is_int($expect)) {
+            return $got === $expect;
+        }
+        return (float) $got === (float) $expect;
+    }
+    return $got === $expect; // strings
+}
+
+$doc = json_decode(file_get_contents($VECTORS_PATH), true);
+bf_assert(!empty($doc['cases']), 'vectors.json contains no cases');
+
+$seenDeclarations = [];
+
+foreach ($doc['cases'] as $case) {
+    $fn = $case['fn'];
+    $note = $case['note'];
+    $args = $case['args'];
+    $expect = $case['expect'];
+    $key = "{$fn}/{$note}";
+
+    if (isset($UNSUPPORTED[$fn])) {
+        bf_skip($key, "unsupported on this backend: {$UNSUPPORTED[$fn]}");
+        continue;
+    }
+
+    $divergence = $DIVERGENCES[$key] ?? null;
+
+    bf_test($key, function () use ($bf, $fn, $args, $expect, $key, $divergence, &$seenDeclarations) {
+        if ($divergence !== null && !empty($divergence['throws'])) {
+            $seenDeclarations[$key] = true;
+            $exceptionClass = $divergence['exception'] ?? \Throwable::class;
+            try {
+                bfv_call($bf, $fn, $args);
+                bf_assert(false, "expected {$exceptionClass} but no exception was thrown ({$divergence['reason']})");
+            } catch (\Throwable $e) {
+                bf_assert(
+                    $e instanceof $exceptionClass,
+                    "expected {$exceptionClass}, got " . get_class($e) . ": {$e->getMessage()}"
+                );
+            }
+            return;
+        }
+
+        $got = bfv_call($bf, $fn, $args);
+
+        if ($divergence !== null) {
+            $seenDeclarations[$key] = true;
+            bf_assert(!bfv_match($got, $expect), "stale divergence declaration for '{$key}' -- the backend now matches JS; remove it");
+            $want = $divergence['expect'];
+            if (is_array($want) && array_key_exists('$num', $want) && count($want) === 1) {
+                bf_assert(bfv_match($got, $want), "{$key} (declared divergence: {$divergence['reason']}): got " . bf_fmt($got) . ', want ' . bf_fmt($want));
+            } elseif ((is_int($want) || is_float($want)) && (is_int($got) || is_float($got))) {
+                bf_assert((float) $got === (float) $want, "{$key} (declared divergence): expected " . bf_fmt($want) . ', got ' . bf_fmt($got));
+            } else {
+                bf_assert_eq($got, $want, "{$key} (declared divergence: {$divergence['reason']})");
+            }
+            return;
+        }
+
+        bf_assert(bfv_match($got, $expect), "{$key}: got " . bf_fmt($got) . ', want ' . bf_fmt($expect));
+    });
+}
+
+$stale = array_diff(array_keys($DIVERGENCES), array_keys($seenDeclarations));
+bf_test('no stale divergence declarations', function () use ($stale) {
+    bf_assert($stale === [], 'divergence declarations match no vector case -- renamed note? ' . implode(', ', $stale));
+});
+
+return bf_finish();

package/tests/test_omit.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * `BarefootJS::omit` -- object-rest destructure residual (#2087 Phase B).
+ *
+ * Backs the Twig adapter's `.map(({ id, title, ...rest }) => ...)` lowering
+ * (`twig-adapter.ts`'s `renderLoop`): each loop iteration binds `rest` to
+ * `bf.omit(item, [excludeKeys])`, a TRUE residual hash (every key of the
+ * item except the ones the pattern destructured explicitly), not an alias
+ * of the whole item. Every template-adapter runtime ships the same helper
+ * under the same contract (#2087 Phase B: Go `bf_omit`, shared Perl
+ * `BarefootJS::omit`, Python/Rust `bf.omit`) -- except ERB, which uses
+ * Ruby's native `Hash#except`. Only the JS/CSR side has no `omit`: it
+ * materializes the residual with a real destructure IIFE instead.
+ */
+
+require_once __DIR__ . '/_harness.php';
+bf_require_runtime();
+bf_reset();
+
+use Barefoot\BarefootJS;
+
+$bf = new BarefootJS(null, ['backend' => new class {
+    public function mark_raw($s)
+    {
+        return $s;
+    }
+}]);
+
+bf_test('basic shapes', function () use ($bf) {
+    bf_assert_eq($bf->omit(null, ['id']), []);
+    bf_assert_eq($bf->omit('not a bag', ['id']), []);
+    bf_assert_eq($bf->omit([], ['id']), []);
+    bf_assert_eq($bf->omit(['id' => 'a', 'flag' => 'x'], []), ['id' => 'a', 'flag' => 'x']);
+});
+
+bf_test('excludes the destructured sibling keys, keeps the rest', function () use ($bf) {
+    $item = ['id' => 't1', 'title' => 'one', 'data-priority' => 'high', 'tag' => 'urgent'];
+    bf_assert_eq($bf->omit($item, ['id', 'title']), ['data-priority' => 'high', 'tag' => 'urgent']);
+});
+
+bf_test('accepts a stdClass bag (JSON-decoded loop item shape)', function () use ($bf) {
+    $item = json_decode('{"id": "t1", "title": "one", "flag": "a"}');
+    bf_assert_eq($bf->omit($item, ['id', 'title']), ['flag' => 'a']);
+});
+
+bf_test('excluding every key yields an empty residual', function () use ($bf) {
+    bf_assert_eq($bf->omit(['id' => 'a'], ['id']), []);
+});
+
+bf_test('an exclude key absent from the bag is a no-op', function () use ($bf) {
+    bf_assert_eq($bf->omit(['id' => 'a'], ['nope']), ['id' => 'a']);
+});
+
+return bf_finish();