@barefootjs/perl 0.16.0 → 0.17.1

package/lib/BarefootJS.pm

@@ -1,5 +1,5 @@
 package BarefootJS;
-our $VERSION = "0.15.2";
+our $VERSION = "0.17.0";
 use strict;
 use warnings;
 use utf8;
@@ -8,6 +8,7 @@ no warnings 'experimental::signatures';
 
 use POSIX ();
 use Scalar::Util qw(looks_like_number weaken);
+use BarefootJS::Evaluator ();
 
 # NOTE: This runtime is template-engine-agnostic AND framework-agnostic by
 # design, so it can ship as a standalone CPAN distribution. It depends only on
@@ -580,8 +581,14 @@ sub round ($self, $value) {
 # receiver shapes apart without TS type inference, so both lower to
 # the same IR node (`array-method` / method `includes`). This helper
 # dispatches at the Perl level via `ref()`:
-#   - ARRAY ref:  scan elements with `eq`; one defined-vs-undef
-#                 hop matches JS's `===` for null/undefined.
+#   - ARRAY ref:  scan elements with `BarefootJS::Evaluator::_same_value_zero`,
+#                 matching `Array.prototype.includes`'s SameValueZero
+#                 semantics (no cross-type coercion, e.g. `[2].includes("2")`
+#                 is false; NaN matches NaN) — the same algorithm the
+#                 evaluator's serialized-callback path already uses for
+#                 `.includes`, so both positions agree. This used to be a
+#                 stringy `eq` scan, which coerced numbers to strings
+#                 (`[2].includes("2")` was true) and diverged from JS.
 #   - scalar:     `index($recv, $sub) != -1`, with both args
 #                 coerced through `// ''` so an undef receiver /
 #                 needle doesn't trip Perl's substr warning.
@@ -592,11 +599,7 @@ sub round ($self, $value) {
 sub includes ($self, $recv, $elem) {
     if (ref($recv) eq 'ARRAY') {
         for my $item (@$recv) {
-            if (!defined $item) {
-                return 1 if !defined $elem;
-                next;
-            }
-            return 1 if defined $elem && $item eq $elem;
+            return 1 if BarefootJS::Evaluator::_same_value_zero($item, $elem);
         }
         return 0;
     }
@@ -1010,6 +1013,53 @@ sub replace ($self, $recv, $pattern, $replacement) {
     return substr($s, 0, $i) . $n . substr($s, $i + CORE::length($o));
 }
 
+# `queryHref(base, { … })` (#2042) — build `"$base?k=v&…"` from a flat list of
+# (guard, key, value) triples. A pair is included iff its guard is truthy AND
+# its value is a non-empty string, mirroring the client `queryHref`'s `if
+# (value)` over string values: the adapter passes the guard `1` for a plain
+# `key: v`, or the lowered condition for `key: cond ? v : undefined`. Repeating a
+# key overwrites the value at its first position (`URLSearchParams.set`
+# semantics).
+#
+# A value may instead be an array ref, which APPENDS one pair per non-empty
+# member (`{ tag => ['a','b'] }` → `tag=a&tag=b`, i.e. `URLSearchParams.append`);
+# empty members are skipped, so an empty/all-empty array contributes nothing.
+#
+# Keys/values are form-encoded to equal the browser render byte-for-byte; no
+# surviving pair yields the bare base.
+sub query ($self, $base, @triples) {
+    my $b = defined $base && !ref($base) ? "$base" : '';
+    my (@pairs, %pos);
+    my $i = 0;
+    while ($i + 2 < @triples) {
+        my ($guard, $key, $val) = @triples[$i, $i + 1, $i + 2];
+        $i += 3;
+        next unless $guard;
+        $key = defined $key && !ref($key) ? "$key" : '';
+        if (ref($val) eq 'ARRAY') {
+            # Append each non-empty member; appended pairs never overwrite, so
+            # they don't participate in the set()-position map.
+            for my $m (@$val) {
+                my $s = defined $m && !ref($m) ? "$m" : '';
+                next if $s eq '';
+                push @pairs, [$key, $s];
+            }
+            next;
+        }
+        $val = defined $val && !ref($val) ? "$val" : '';
+        next if $val eq '';
+        if (exists $pos{$key}) {
+            $pairs[$pos{$key}][1] = $val;
+        }
+        else {
+            $pos{$key} = scalar @pairs;
+            push @pairs, [$key, $val];
+        }
+    }
+    return $b unless @pairs;
+    return "$b?" . CORE::join('&', map { _form_escape($_->[0]) . '=' . _form_escape($_->[1]) } @pairs);
+}
+
 # `String.prototype.repeat(n)` — the receiver concatenated n times
 # (#1448 Tier B), via Perl's `x` operator. JS throws RangeError for a
 # negative count, but SSR templates degrade to the empty string rather
@@ -1089,6 +1139,56 @@ sub pad_end ($self, $recv, $target, $pad = undef) {
 # A future `nulls => 'first' | 'last'` knob can land per key without
 # churn — the opts hash is the right place to grow.
 
+# Evaluator-driven sort / reduce (#2018): the comparator / reducer body rides
+# as a serialized-ParsedExpr JSON string and is evaluated per element, delegating
+# to the shared BarefootJS::Evaluator. The adapter emits `bf->sort_eval(...)` /
+# `bf->reduce_eval(...)` for any pure comparator / reducer body; a body it can't
+# model (e.g. localeCompare) keeps the legacy `bf->sort` / `bf->reduce` path.
+sub sort_eval ($self, $recv, $cmp_json, $param_a, $param_b, $base_env = {}) {
+    return BarefootJS::Evaluator::sort_by_json($recv, $cmp_json, $param_a, $param_b, $base_env);
+}
+
+sub reduce_eval ($self, $recv, $body_json, $acc_name, $item_name, $init, $direction = 'left', $base_env = {}) {
+    return BarefootJS::Evaluator::fold_json($recv, $body_json, $acc_name, $item_name, $init, $direction, $base_env);
+}
+
+# Evaluator-driven higher-order predicates (#2018, P2): the predicate body
+# rides as a serialized-ParsedExpr JSON string evaluated per element, delegating
+# to the shared BarefootJS::Evaluator. The adapter emits `bf->filter_eval(...)`
+# etc. for any pure predicate; a body it can't model (e.g. a method-call
+# predicate) keeps the legacy `grep` / `bf->find` path. `find_eval` /
+# `find_index_eval` take a `$forward` flag (false → findLast / findLastIndex).
+sub filter_eval ($self, $recv, $pred_json, $param, $base_env = {}) {
+    return BarefootJS::Evaluator::filter_json($recv, $pred_json, $param, $base_env);
+}
+
+sub every_eval ($self, $recv, $pred_json, $param, $base_env = {}) {
+    return BarefootJS::Evaluator::every_json($recv, $pred_json, $param, $base_env);
+}
+
+sub some_eval ($self, $recv, $pred_json, $param, $base_env = {}) {
+    return BarefootJS::Evaluator::some_json($recv, $pred_json, $param, $base_env);
+}
+
+sub find_eval ($self, $recv, $pred_json, $param, $forward = 1, $base_env = {}) {
+    return BarefootJS::Evaluator::find_json($recv, $pred_json, $param, $forward, $base_env);
+}
+
+sub find_index_eval ($self, $recv, $pred_json, $param, $forward = 1, $base_env = {}) {
+    return BarefootJS::Evaluator::find_index_json($recv, $pred_json, $param, $forward, $base_env);
+}
+
+sub flat_map_eval ($self, $recv, $proj_json, $param, $base_env = {}) {
+    return BarefootJS::Evaluator::flat_map_json($recv, $proj_json, $param, $base_env);
+}
+
+# Value-producing `.map(cb)` (#2073): project each element through the
+# serialized projection body, one result per element (no flatten). Composes
+# through the array-method chain (`.map(cb).join(' ')`).
+sub map_eval ($self, $recv, $proj_json, $param, $base_env = {}) {
+    return BarefootJS::Evaluator::map_json($recv, $proj_json, $param, $base_env);
+}
+
 sub sort ($self, $recv, $opts = {}) {
     return [] unless ref($recv) eq 'ARRAY';
 
@@ -1266,6 +1366,18 @@ sub _to_attr_name ($key) {
     return $out;
 }
 
+sub _form_escape ($s) {
+    # application/x-www-form-urlencoded serialisation, matching the browser's
+    # `URLSearchParams` (which the SSR query render must equal): keep ASCII
+    # alphanumerics and `* - . _`; encode every other byte as `%XX` (UPPER hex);
+    # space → `+`. Non-ASCII is encoded byte-wise over its UTF-8 bytes.
+    my $bytes = defined $s ? "$s" : '';
+    utf8::encode($bytes) if utf8::is_utf8($bytes);
+    $bytes =~ s/([^A-Za-z0-9*\-._ ])/sprintf('%%%02X', ord($1))/ge;
+    $bytes =~ tr/ /+/;
+    return $bytes;
+}
+
 sub _html_escape ($value) {
     # HTML attribute-value escape for SSR string emission. The
     # spread bag's values reach the browser as part of a generated

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/perl",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "description": "BarefootJS engine-agnostic Perl runtime (BarefootJS.pm) — pluggable rendering backend; the shared basis for Mojolicious and other Perl framework integrations",
   "type": "module",
   "files": [

package/t/eval_vectors.t

@@ -0,0 +1,113 @@
+use strict;
+use warnings;
+use Test::More;
+use FindBin;
+use File::Spec;
+use JSON::PP ();
+use B ();
+use Scalar::Util qw(looks_like_number);
+
+use lib "$FindBin::Bin/../lib";
+use BarefootJS::Evaluator;
+
+# Golden ParsedExpr-evaluator vectors (issue #2018, spec/compiler.md
+# "ParsedExpr Evaluator Semantics"), generated from the JS reference
+# evaluator and shared with the Go evaluator. The file is not shipped in
+# the CPAN dist — packages/adapter-tests only exists in a monorepo
+# checkout — so skip everywhere else.
+my $vectors_path = File::Spec->catfile(
+    $FindBin::Bin, '..', '..', 'adapter-tests', 'helper-vectors', 'eval-vectors.json'
+);
+plan skip_all => 'eval vectors not available outside the monorepo checkout'
+    unless -e $vectors_path;
+
+my $doc = do {
+    open my $fh, '<:raw', $vectors_path or die "open $vectors_path: $!";
+    local $/;
+    JSON::PP->new->decode(<$fh>);
+};
+
+die "eval-vectors.json contains no cases" unless @{ $doc->{cases} || [] };
+
+# The evaluator is JS-faithful by contract, so there are NO Perl-side
+# divergences here (unlike the bf->string / number helper vectors). Each
+# case's real ParsedExpr tree, evaluated against its environment, must
+# reproduce the JS-computed expect exactly — same input → same output as Go.
+for my $case (@{ $doc->{cases} }) {
+    my $note   = $case->{note};
+    my $expr   = $case->{expr};
+    my $env    = $case->{env};
+    my $expect = $case->{expect};
+
+    my $got = eval { BarefootJS::Evaluator::evaluate($expr, $env) };
+    if (my $err = $@) {
+        fail("$note died: $err");
+        next;
+    }
+    ok(_match($got, $expect), $note)
+        or diag('got ' . explain_value($got) . ', want ' . explain_value($expect));
+}
+
+done_testing;
+
+# _is_real_number: true only when the scalar is an actual number (SV carries
+# IOK/NOK), NOT a numeric-looking string. JSON::PP decodes a JSON number to
+# IOK/NOK and a JSON string to a POK-only scalar, so this tells the JS *number*
+# 42 from the JS *string* "42" — the distinction the evaluator must preserve.
+# (looks_like_number can't: it is true for the string "42" too.)
+sub _is_real_number {
+    my ($v) = @_;
+    return 0 unless defined $v && !ref $v;
+    return (B::svref_2object(\$v)->FLAGS & (B::SVf_IOK | B::SVf_NOK)) ? 1 : 0;
+}
+
+# _match: boolean form of the spec's value-compat comparison against a
+# JSON-decoded expect — non-finite sentinel hashes, booleans by truthiness,
+# numbers numerically, arrays/hashes recursively, strings by eq.
+sub _match {
+    my ($got, $expect) = @_;
+    return !defined $got if !defined $expect;
+    if (ref $expect eq 'HASH' && exists $expect->{'$num'}) {
+        my $kind = $expect->{'$num'};
+        return 0 unless defined $got && looks_like_number($got);
+        return $got != $got ? 1 : 0 if $kind eq 'NaN';
+        my $inf = 9**9**9;
+        return $got == ($kind eq 'Infinity' ? $inf : -$inf) ? 1 : 0;
+    }
+    if (JSON::PP::is_bool($expect)) {
+        # The result must itself be a JS boolean (JSON::PP::Boolean), not a
+        # truthy/falsy 1/0 — otherwise a boolean-valued expression returning
+        # the number 1 instead of `true` would pass and mask the divergence.
+        return 0 unless JSON::PP::is_bool($got);
+        return (!!$got eq !!$expect) ? 1 : 0;
+    }
+    if (ref $expect eq 'ARRAY') {
+        return 0 unless ref $got eq 'ARRAY' && @$got == @$expect;
+        _match($got->[$_], $expect->[$_]) or return 0 for 0 .. $#$expect;
+        return 1;
+    }
+    if (ref $expect eq 'HASH') {
+        return 0 unless ref $got eq 'HASH' && keys %$got == keys %$expect;
+        for my $k (keys %$expect) {
+            return 0 unless exists $got->{$k};
+            _match($got->{$k}, $expect->{$k}) or return 0;
+        }
+        return 1;
+    }
+    return 0 if !defined $got || ref $got;
+    # Numeric == only when BOTH are real numbers (not numeric-looking strings),
+    # so a string-vs-number mismatch fails: e.g. String(42) must return the
+    # string "42", and the evaluator returning the number 42 must NOT pass.
+    my $want_num = _is_real_number($expect);
+    return 0 if $want_num != _is_real_number($got);
+    return ($got == $expect ? 1 : 0) if $want_num;
+    return ($got eq $expect) ? 1 : 0;
+}
+
+sub explain_value {
+    my ($v) = @_;
+    return 'undef' unless defined $v;
+    return JSON::PP->new->canonical->allow_nonref->allow_blessed->convert_blessed->encode($v)
+        if ref $v;
+    return "'$v'";
+}

package/t/evaluator.t

@@ -0,0 +1,333 @@
+use strict;
+use warnings;
+use Test::More;
+use FindBin;
+use JSON::PP ();
+
+use lib "$FindBin::Bin/../lib";
+use BarefootJS::Evaluator;
+
+# Hand-built ParsedExpr constructors for the fold / sort_by trees, mirroring
+# the Go eval_test.go demonstrations so the two backends prove the SAME
+# restriction-lifting on the SAME shapes.
+sub nid  { return { kind => 'identifier', name => $_[0] } }
+sub nmem { return { kind => 'member', object => $_[0], property => $_[1], computed => JSON_false() } }
+sub nbin { return { kind => 'binary', op => $_[0], left => $_[1], right => $_[2] } }
+sub nstr { return { kind => 'literal', value => $_[0], literalType => 'string' } }
+
+sub ncall_math {
+    my ($fn, $arg) = @_;
+    return { kind => 'call', callee => nmem(nid('Math'), $fn), args => [$arg] };
+}
+
+sub nincludes {
+    my ($object, $needle) = @_;
+    return { kind => 'array-method', method => 'includes', object => $object, args => [$needle] };
+}
+
+# A plain false for the `computed` flag; the evaluator only checks truthiness.
+sub JSON_false { return 0 }
+
+# fold lifts bf_reduce's op restriction and acc-canonical form: a reducer body
+# that mixes acc with a product of two fields is impossible in the +/*
+# self/field catalogue but trivial for the evaluator.
+subtest 'fold: arbitrary reducer body (acc + item.price * item.qty)' => sub {
+    my $body = nbin('+',
+        nid('acc'),
+        nbin('*', nmem(nid('item'), 'price'), nmem(nid('item'), 'qty')),
+    );
+    my $items = [ { price => 5, qty => 3 }, { price => 2, qty => 4 } ];
+    is(BarefootJS::Evaluator::fold($items, $body, 'acc', 'item', 0, 'left'),
+        23, '0 + 5*3 + 2*4');
+};
+
+# reduceRight is observable for string concatenation; the same body folds both
+# directions.
+subtest 'fold: direction is observable for string concat' => sub {
+    my $body  = nbin('+', nid('acc'), nid('item'));
+    my $items = [ 'a', 'b', 'c' ];
+    is(BarefootJS::Evaluator::fold($items, $body, 'acc', 'item', '', 'left'),  'abc', 'left');
+    is(BarefootJS::Evaluator::fold($items, $body, 'acc', 'item', '', 'right'), 'cba', 'right');
+};
+
+# sort_by lifts bf_sort's comparator pattern restriction: a comparator that
+# calls Math.abs on each operand's field is outside the subtraction /
+# localeCompare / relational-ternary catalogue, but is just another pure
+# expression to the evaluator.
+subtest 'sort_by: arbitrary comparator body (abs-of-field difference)' => sub {
+    my $cmp = nbin('-',
+        ncall_math('abs', nmem(nid('a'), 'v')),
+        ncall_math('abs', nmem(nid('b'), 'v')),
+    );
+    my $items  = [ { v => -5 }, { v => 3 }, { v => -1 } ];
+    my $sorted = BarefootJS::Evaluator::sort_by($items, $cmp, 'a', 'b');
+    is_deeply([ map { $_->{v} } @$sorted ], [ -1, 3, -5 ], 'ascending by |v|');
+};
+
+# Descending is just a reversed comparator body — no separate direction knob.
+subtest 'sort_by: descending via a reversed comparator' => sub {
+    my $cmp = nbin('-', nmem(nid('b'), 'x'), nmem(nid('a'), 'x'));
+    my $items  = [ { x => 10 }, { x => 30 }, { x => 20 } ];
+    my $sorted = BarefootJS::Evaluator::sort_by($items, $cmp, 'a', 'b');
+    is_deeply([ map { $_->{x} } @$sorted ], [ 30, 20, 10 ], 'descending by x');
+};
+
+# Non-finite coercion stays JS-faithful (and matches the Go evaluator):
+# division by zero is ±Infinity / NaN rather than a Perl die, and those
+# values stringify as "Infinity" / "-Infinity" / "NaN" (not Perl's "Inf").
+subtest 'non-finite: division by zero and JS stringification' => sub {
+    my $div = sub {
+        my ($a, $b) = @_;
+        BarefootJS::Evaluator::evaluate(
+            nbin('/', { kind => 'identifier', name => 'a' }, { kind => 'identifier', name => 'b' }),
+            { a => $a, b => $b },
+        );
+    };
+    my $inf = 9**9**9;
+    is($div->(1, 0),  $inf,  '1/0 is +Infinity, not a die');
+    is($div->(-1, 0), -$inf, '-1/0 is -Infinity');
+    my $nan = $div->(0, 0);
+    ok($nan != $nan, '0/0 is NaN');
+
+    is(BarefootJS::Evaluator::_to_string($inf),    'Infinity',  'String(Infinity)');
+    is(BarefootJS::Evaluator::_to_string(-$inf),   '-Infinity', 'String(-Infinity)');
+    is(BarefootJS::Evaluator::_to_string($inf - $inf), 'NaN',   'String(NaN)');
+};
+
+# Captured free vars flow through $base_env (mirrors the Go FoldEval/SortEval
+# baseEnv test) — a reducer / comparator body can reference an outer const.
+subtest 'captured free vars via base_env' => sub {
+    # reduce: acc + item * factor, with `factor` captured.
+    my $body = nbin('+', nid('acc'), nbin('*', nid('item'), nid('factor')));
+    my $sum = BarefootJS::Evaluator::fold([1, 2, 3], $body, 'acc', 'item', 0, 'left', { factor => 10 });
+    is($sum, 60, '0 + 1*10 + 2*10 + 3*10 with captured factor');
+
+    # sort by distance from a captured `pivot`: |a-pivot| - |b-pivot|.
+    my $cmp = nbin('-',
+        ncall_math('abs', nbin('-', nid('a'), nid('pivot'))),
+        ncall_math('abs', nbin('-', nid('b'), nid('pivot'))),
+    );
+    my $sorted = BarefootJS::Evaluator::sort_by([1, 8, 4], $cmp, 'a', 'b', { pivot => 5 });
+    is_deeply($sorted, [4, 8, 1], 'ascending by distance from captured pivot');
+};
+
+# Boolean-valued operators return JS booleans (JSON::PP::Boolean), not 1/0 —
+# matching the Go evaluator, so they stringify "true"/"false" and concatenate
+# as JS does.
+subtest 'boolean-valued ops return JS booleans, not 1/0' => sub {
+    my $lt = BarefootJS::Evaluator::evaluate(nbin('<', nid('a'), nid('b')), { a => 1, b => 2 });
+    ok(JSON::PP::is_bool($lt), 'a < b is a JS boolean');
+    is(BarefootJS::Evaluator::_to_string($lt), 'true', 'String(a < b) is "true", not "1"');
+
+    my $cat = BarefootJS::Evaluator::evaluate(
+        nbin('+', nstr('x'), nbin('<', nid('a'), nid('b'))), { a => 1, b => 2 });
+    is($cat, 'xtrue', "'x' + (a < b) is 'xtrue', not 'x1'");
+
+    my $eq = BarefootJS::Evaluator::evaluate(nbin('===', nid('a'), nid('b')), { a => 1, b => 1 });
+    ok(JSON::PP::is_bool($eq), '1 === 1 is a JS boolean');
+
+    my $not = BarefootJS::Evaluator::evaluate({ kind => 'unary', op => '!', argument => nstr('') }, {});
+    is(BarefootJS::Evaluator::_to_string($not), 'true', 'String(!"") is "true"');
+
+    my $b = BarefootJS::Evaluator::evaluate(
+        { kind => 'call', callee => nid('Boolean'), args => [nstr('')] }, {});
+    ok(JSON::PP::is_bool($b), 'Boolean("") is a JS boolean');
+    is(BarefootJS::Evaluator::_to_string($b), 'false', 'String(Boolean("")) is "false", not "0"');
+
+    # `.length` is a string/array property only; a numeric scalar has none.
+    my $len = BarefootJS::Evaluator::evaluate(nmem(nid('n'), 'length'), { n => 123 });
+    ok(!defined $len, '(123).length is null, not 3');
+};
+
+# `.includes` (#2075) is the one `array-method` in the evaluator subset,
+# dispatching on the receiver type like the SSR template lowering does at
+# runtime (`bf_includes` / `$bf->includes`): array → SameValueZero membership
+# (the same value rules as `===`, so a numeric 2 does NOT match the string
+# "2"); string → substring search; anything else degrades to false rather
+# than dying.
+subtest 'array-method includes' => sub {
+    my $hit = BarefootJS::Evaluator::evaluate(nincludes(nid('tags'), nstr('go')), { tags => [ 'perl', 'go' ] });
+    ok(JSON::PP::is_bool($hit), 'array hit is a JS boolean');
+    ok($hit, 'array .includes: hit');
+
+    my $miss = BarefootJS::Evaluator::evaluate(nincludes(nid('tags'), nstr('rust')), { tags => [ 'perl', 'go' ] });
+    ok(JSON::PP::is_bool($miss), 'array miss is a JS boolean');
+    ok(!$miss, 'array .includes: miss');
+
+    # SameValueZero, not loose equality: the numeric element 2 matches the
+    # numeric needle 2, but the string needle "2" (a different JS type) does
+    # not — mirroring `===`'s type-sensitivity.
+    my $num_hit = BarefootJS::Evaluator::evaluate(nincludes(nid('nums'), { kind => 'literal', value => 2 }), { nums => [ 1, 2, 3 ] });
+    ok($num_hit, 'array .includes: numeric element hit');
+    my $num_vs_string = BarefootJS::Evaluator::evaluate(nincludes(nid('nums'), nstr('2')), { nums => [ 1, 2, 3 ] });
+    ok(!$num_vs_string, 'array .includes: numeric element does not match a string needle');
+
+    my $sub = BarefootJS::Evaluator::evaluate(nincludes(nid('name'), nstr('ar')), { name => 'bare' });
+    ok($sub, 'string .includes: substring hit');
+
+    # A non-array, non-string receiver (number, null, object) is not a JS
+    # `.includes` target; the evaluator degrades to false rather than dying.
+    my $scalar_recv = BarefootJS::Evaluator::evaluate(nincludes(nid('n'), { kind => 'literal', value => 1 }), { n => 42 });
+    ok(!$scalar_recv, 'non-collection receiver (number) is false, not a die');
+    my $null_recv = BarefootJS::Evaluator::evaluate(nincludes(nid('n'), nstr('x')), { n => undef });
+    ok(!$null_recv, 'non-collection receiver (null) is false, not a die');
+};
+
+# sort_by tolerates a non-array receiver by returning an empty arrayref (the
+# BarefootJS->sort convention), never undef — so callers can always deref it.
+subtest 'sort_by non-array receiver returns []' => sub {
+    my $cmp = nbin('-', nid('a'), nid('b'));
+    is_deeply(BarefootJS::Evaluator::sort_by(undef, $cmp, 'a', 'b'), [], 'undef receiver → []');
+    is_deeply(BarefootJS::Evaluator::sort_by(42, $cmp, 'a', 'b'), [], 'scalar receiver → []');
+};
+
+# sort_by is stable: equal-comparing elements keep their input order. The
+# explicit index tie-break makes this independent of the `sort` pragma /
+# build, matching Go's sort.SliceStable.
+subtest 'sort_by is stable for equal keys' => sub {
+    my $cmp = nbin('-', nmem(nid('a'), 'k'), nmem(nid('b'), 'k'));
+    # All-equal keys → input order preserved.
+    my $eq = BarefootJS::Evaluator::sort_by(
+        [ { k => 1, id => 'a' }, { k => 1, id => 'b' }, { k => 1, id => 'c' } ],
+        $cmp, 'a', 'b');
+    is_deeply([ map { $_->{id} } @$eq ], [ 'a', 'b', 'c' ], 'equal keys keep input order');
+    # Mixed keys → sorted by key, ties stable (x before z).
+    my $mixed = BarefootJS::Evaluator::sort_by(
+        [ { k => 2, id => 'x' }, { k => 1, id => 'y' }, { k => 2, id => 'z' } ],
+        $cmp, 'a', 'b');
+    is_deeply([ map { $_->{id} } @$mixed ], [ 'y', 'x', 'z' ], 'tie (x,z) stays in input order');
+};
+
+# fold_json / sort_by_json are the JSON-string seam the adapters emit into:
+# the serialized ParsedExpr body travels as a `bf->reduce_eval` / `bf->sort_eval`
+# argument and is decoded here, then handed to fold / sort_by. These exercise
+# the exact shapes the #2018 EXPR2 reduce/sort migration emits (field access
+# over hashref rows keyed by the raw JS prop name), with the captured-env arg.
+subtest 'fold_json / sort_by_json decode a JSON body and evaluate it' => sub {
+    my @rows = ({ duration => 95 }, { duration => 213 }, { duration => 185 });
+
+    # reduce: sum + t.duration, seed 0 → 493
+    my $reduce = JSON::PP->new->encode(
+        nbin('+', nid('sum'), nmem(nid('t'), 'duration')));
+    is(BarefootJS::Evaluator::fold_json(\@rows, $reduce, 'sum', 't', 0, 'left', {}),
+        493, 'fold_json sums a field');
+
+    # reduceRight concat is order-observable: cba, not abc.
+    my @labels = ({ label => 'a' }, { label => 'b' }, { label => 'c' });
+    my $concat = JSON::PP->new->encode(
+        nbin('+', nid('acc'), nmem(nid('x'), 'label')));
+    is(BarefootJS::Evaluator::fold_json(\@labels, $concat, 'acc', 'x', '', 'left', {}),
+        'abc', 'fold_json concat left → abc');
+    is(BarefootJS::Evaluator::fold_json(\@labels, $concat, 'acc', 'x', '', 'right', {}),
+        'cba', 'fold_json concat right → cba');
+
+    # sort: a.duration - b.duration → ascending
+    my $cmp = JSON::PP->new->encode(
+        nbin('-', nmem(nid('a'), 'duration'), nmem(nid('b'), 'duration')));
+    my $sorted = BarefootJS::Evaluator::sort_by_json(\@rows, $cmp, 'a', 'b', {});
+    is_deeply([ map { $_->{duration} } @$sorted ], [ 95, 185, 213 ],
+        'sort_by_json orders by a field');
+};
+
+# The #2018 P2 higher-order predicate helpers evaluate an arbitrary pure
+# predicate body per element, generalizing bf_filter / bf_find / bf_every /
+# bf_some. Mirrors the Go TestPredicateEvalHelpers shapes (u => u.age >= 18).
+subtest 'filter / every / some / find / find_index over a predicate body' => sub {
+    my @rows = ({ age => 15 }, { age => 30 }, { age => 18 });
+    my $pred = nbin('>=', nmem(nid('u'), 'age'),
+        { kind => 'literal', value => 18, literalType => 'number' });
+
+    my $f = BarefootJS::Evaluator::filter(\@rows, $pred, 'u');
+    is_deeply([ map { $_->{age} } @$f ], [ 30, 18 ], 'filter keeps age >= 18');
+
+    is(BarefootJS::Evaluator::some(\@rows, $pred, 'u'), 1, 'some → true');
+    is(BarefootJS::Evaluator::every(\@rows, $pred, 'u'), 0, 'every → false (15 < 18)');
+
+    is(BarefootJS::Evaluator::find(\@rows, $pred, 'u', 1)->{age}, 30, 'find forward → 30');
+    is(BarefootJS::Evaluator::find(\@rows, $pred, 'u', 0)->{age}, 18, 'findLast → 18');
+    is(BarefootJS::Evaluator::find_index(\@rows, $pred, 'u', 1), 1, 'findIndex → 1');
+    is(BarefootJS::Evaluator::find_index(\@rows, $pred, 'u', 0), 2, 'findLastIndex → 2');
+
+    # Empty receiver: every vacuously true, some false, find undef / index -1.
+    is(BarefootJS::Evaluator::every([], $pred, 'u'), 1, 'every(empty) → true');
+    is(BarefootJS::Evaluator::some([], $pred, 'u'), 0, 'some(empty) → false');
+    ok(!defined BarefootJS::Evaluator::find([], $pred, 'u'), 'find(empty) → undef');
+    is(BarefootJS::Evaluator::find_index([], $pred, 'u'), -1, 'find_index(empty) → -1');
+
+    # JSON seam: the body arrives as the string the adapter emits. Cover more
+    # than filter_json so each *_json entry point is pinned (Copilot review
+    # #2032).
+    my $json = JSON::PP->new->encode($pred);
+    my $fj = BarefootJS::Evaluator::filter_json(\@rows, $json, 'u');
+    is_deeply([ map { $_->{age} } @$fj ], [ 30, 18 ], 'filter_json decodes + filters');
+    is(BarefootJS::Evaluator::every_json(\@rows, $json, 'u'), 0, 'every_json → false');
+    is(BarefootJS::Evaluator::some_json(\@rows, $json, 'u'),  1, 'some_json → true');
+    is(BarefootJS::Evaluator::find_json(\@rows, $json, 'u', 1)->{age}, 30, 'find_json forward → 30');
+    is(BarefootJS::Evaluator::find_index_json(\@rows, $json, 'u', 0), 2, 'find_index_json backward → 2');
+
+    # Captured base_env: a predicate `u => u.age >= threshold` reads the outer
+    # `threshold`, and changing it changes the result — pins the capture
+    # plumbing (Copilot review #2032).
+    my $cap = nbin('>=', nmem(nid('u'), 'age'), nid('threshold'));
+    my $hi  = BarefootJS::Evaluator::filter(\@rows, $cap, 'u', { threshold => 18 });
+    my $lo  = BarefootJS::Evaluator::filter(\@rows, $cap, 'u', { threshold => 100 });
+    is(scalar(@$hi), 2, 'captured threshold 18 keeps 2');
+    is(scalar(@$lo), 0, 'captured threshold 100 keeps 0');
+    is(BarefootJS::Evaluator::find_index(\@rows, $cap, 'u', 1, { threshold => 100 }), -1,
+        'find_index with unmet captured threshold → -1');
+};
+
+# #2018 P3: flat_map projects each element through a projection body and
+# flattens one level — a field projection yielding an arrayref contributes its
+# elements; an array-literal (tuple) projection contributes its leaves. Mirrors
+# the Go TestFlatMapEval shapes.
+subtest 'flat_map projects + flattens one level' => sub {
+    my @rows = ({ tags => [ 'a', 'b' ] }, { tags => [ 'c' ] });
+    my $field = nmem(nid('i'), 'tags');
+    is_deeply(BarefootJS::Evaluator::flat_map(\@rows, $field, 'i'), [ 'a', 'b', 'c' ],
+        'field projection flattens the per-item arrays');
+
+    my @pts = ({ x => 1, y => 2 }, { x => 3, y => 4 });
+    my $tuple = {
+        kind     => 'array-literal',
+        elements => [ nmem(nid('p'), 'x'), nmem(nid('p'), 'y') ],
+    };
+    is_deeply(BarefootJS::Evaluator::flat_map(\@pts, $tuple, 'p'), [ 1, 2, 3, 4 ],
+        'array-literal projection flattens the leaf tuples');
+
+    # JSON seam.
+    my $fj = BarefootJS::Evaluator::flat_map_json(\@rows,
+        JSON::PP->new->encode($field), 'i');
+    is_deeply($fj, [ 'a', 'b', 'c' ], 'flat_map_json decodes + projects');
+};
+
+# #2073: map_items is the value-producing `.map(cb)` — one result per element,
+# NO flatten (an array-valued projection stays one element). Mirrors the Go
+# TestMapEval shapes.
+subtest 'map_items projects one result per element (no flatten)' => sub {
+    my $tmpl = {
+        kind  => 'template-literal',
+        parts => [
+            { type => 'string',     value => '#' },
+            { type => 'expression', expr  => nid('t') },
+        ],
+    };
+    is_deeply(BarefootJS::Evaluator::map_items([ 'perl', 'go' ], $tmpl, 't'),
+        [ '#perl', '#go' ], 'template-literal projection maps each element');
+
+    my @users = ({ name => 'Ada' }, { name => 'Grace' });
+    my $field = nmem(nid('u'), 'name');
+    is_deeply(BarefootJS::Evaluator::map_items(\@users, $field, 'u'),
+        [ 'Ada', 'Grace' ], 'field projection maps each element');
+
+    my @rows = ({ tags => [ 'a', 'b' ] });
+    is_deeply(BarefootJS::Evaluator::map_items(\@rows, nmem(nid('i'), 'tags'), 'i'),
+        [ [ 'a', 'b' ] ], 'array-valued projection stays ONE element (no flatten)');
+
+    # JSON seam.
+    my $mj = BarefootJS::Evaluator::map_json(\@users,
+        JSON::PP->new->encode($field), 'u');
+    is_deeply($mj, [ 'Ada', 'Grace' ], 'map_json decodes + projects');
+};
+
+done_testing;