From a674c5d1a35b98aebe34391ea7d9677bd3d4ee73 Mon Sep 17 00:00:00 2001
From: Chemi Atlow <chemi@atlow.co.il>
Date: Thu, 13 Aug 2026 16:26:26 +0300
Subject: [PATCH 1/4] test_runner: extend tag filter with boolean expression
 DSL

Upgrades the experimental tag filter introduced by stage 1 to accept a
boolean expression instead of a literal tag name.

Grammar: `and`/`&&`, `or`/`||`, `not`/`!`, parentheses for grouping,
and `*` wildcards inside identifiers. Standard precedence
(`not > and > or`); binary operators are left-associative. Word forms
require whitespace separation; punctuation forms do not. Untagged
tests evaluate `false` for any include expression and `true` for
`not X`, so excluding tags does not accidentally remove untagged
tests.

The flag and `testTagFilters` option are still repeatable; multiple
expressions still AND together. Malformed expressions fail fast at
the parent process at startup.

Tag value validation tightens to reject whitespace, operator
characters (`& | ! ( ) *`), and the reserved words `and`/`or`/`not`
in any casing - a breaking change relative to the stage 1 ship,
acceptable at Stability 1.0 (Early development).

Signed-off-by: atlowChemi <chemi@atlow.co.il>
PR-URL: https://github.com/nodejs/node/pull/63054
Reviewed-By: Moshe Atlow <moshe@atlow.co.il>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
---
 doc/api/cli.md                                |  22 +-
 doc/api/test.md                               |  99 +++-
 doc/node.1                                    |  20 +-
 lib/internal/test_runner/runner.js            |  35 +-
 lib/internal/test_runner/tag_filter.js        | 446 ++++++++++++++++--
 lib/internal/test_runner/utils.js             |  18 +-
 test/parallel/test-runner-tag-filter-cli.mjs  |  81 +++-
 .../test-runner-tag-filter-parser.mjs         | 257 ++++++++++
 test/parallel/test-runner-tags-events.mjs     |   8 +
 .../test-runner-tags-experimental-warning.mjs |   2 +-
 test/parallel/test-runner-tags-validation.mjs |  29 +-
 11 files changed, 920 insertions(+), 97 deletions(-)
 create mode 100644 test/parallel/test-runner-tag-filter-parser.mjs

diff --git a/doc/api/cli.md b/doc/api/cli.md
index 2052f010f4bb..e213d055b8e9 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -1499,7 +1499,7 @@ Enable module mocking in the test runner.
 
 This feature requires `--allow-worker` if used with the [Permission Model][].
 
-### `--experimental-test-tag-filter=<tag>`
+### `--experimental-test-tag-filter='<expr>'`
 
 <!-- YAML
 added:
@@ -1509,14 +1509,20 @@ added:
 
 > Stability: 1.0 - Early development
 
-Run only tests whose tag set contains `<tag>`. Tests declare tags via the
-`tags` option on `test()`, `it()`, `suite()`, or `describe()`; tags
-inherit from suites to nested tests by union. Filtering is
-case-insensitive.
+Run only tests that match the provided boolean tag-filter expression. Tests
+declare tags via the `tags` option on `test()`, `it()`, `suite()`, or
+`describe()`. Tags inherit from suites to nested tests by union.
 
-The flag may be specified more than once; tests must contain **every**
-filter value to run. See [Test tags][] for details on declaring and
-inheriting tags.
+The expression supports boolean operators (`and`/`&&`, `or`/`||`,
+`not`/`!`), parentheses for grouping, and `*` wildcards inside identifiers.
+Standard precedence applies: `not` binds tighter than `and`, which binds
+tighter than `or`. See [Test tags][] for the full grammar and behavior.
+
+The flag may be specified more than once; multiple expressions are combined
+with AND, so a test must satisfy every expression to run.
+
+A malformed expression causes the test runner to exit with a non-zero status
+before running any tests.
 
 ### `--experimental-vfs`
 
diff --git a/doc/api/test.md b/doc/api/test.md
index 8922086884a2..573f2da98f9d 100644
--- a/doc/api/test.md
+++ b/doc/api/test.md
@@ -491,8 +491,8 @@ added:
 
 Tags annotate tests and suites with arbitrary string labels. The
 [`--experimental-test-tag-filter`][] CLI flag (or the `testTagFilters`
-option on [`run()`][]) selects tests whose tag set contains every
-provided filter value.
+option on [`run()`][]) selects tests by a boolean expression over those
+labels.
 
 Tags are an alternative to encoding metadata into test names. They are
 useful for cross-cutting axes such as subsystem, speed bucket, flakiness,
@@ -525,37 +525,89 @@ describe('database', { tags: ['db'] }, () => {
 });
 ```
 
-Tag values must be non-empty strings. Tags are matched case-insensitively;
-the canonical form is lowercase. Duplicates within a single `tags` array
-are collapsed on the lowercased form, preserving the first-seen
-declaration order.
+Tag values must be non-empty strings that contain no whitespace, no
+operator characters (`& | ! ( ) *`), and are not the reserved words
+`'and'`, `'or'`, or `'not'` in any casing. Tags are matched
+case-insensitively; the canonical form is lowercase. Duplicates within a
+single `tags` array are collapsed on the lowercased form, preserving the
+first-seen declaration order.
 
 Hooks (`before`, `after`, `beforeEach`, `afterEach`) do not declare their
 own tags. They run as part of their owning suite, which carries the
 suite's tags.
 
-### Filtering by tag
+### Filtering syntax
 
-Each [`--experimental-test-tag-filter`][] value is a literal tag name. A
-test runs only when its tag set contains that name. The flag may be
-specified more than once; tests must match **every** filter to run. The
-same applies to the `testTagFilters` array on [`run()`][]. Filters are
-case-insensitive and AND'd with [`--test-name-pattern`][],
-[`--test-skip-pattern`][], and `.only` filtering.
+The filter expression supports:
 
-Untagged tests are excluded under any non-empty filter, since the filter
-requires the tag to be present.
+* Identifiers—any non-whitespace, non-operator characters. A literal
+  identifier matches a tag of the same value (case-insensitive).
+* `*` wildcards inside an identifier match any sequence of characters.
+  A bare `*` matches any tagged test.
+* Boolean operators with two equivalent forms:
+  * `and` / `&&`
+  * `or` / `||`
+  * `not` / `!`
+* Parentheses for grouping.
 
-### Reading tags from inside a test
+The word forms (`and`, `or`, `not`) require whitespace separation; the
+punctuation forms do not.
+
+#### Operator precedence
+
+The expression is evaluated with the standard precedence
+`not > and > or`. Binary operators are left-associative.
+
+| Expression     | Equivalent grouping |
+| -------------- | ------------------- |
+| `a or b and c` | `a or (b and c)`    |
+| `not a and b`  | `(not a) and b`     |
+
+Use parentheses to override:
+
+| Expression                     | Selects                                    |
+| ------------------------------ | ------------------------------------------ |
+| `(unit or smoke) and not slow` | unit-or-smoke tests that are not also slow |
+| `db && !flaky`                 | db tests that are not flaky                |
+| `*`                            | every tagged test                          |
+
+#### Untagged tests
+
+Untagged tests behave as if they have an empty tag set. As a result:
+
+| Filter expression        | Untagged test | Why                                              |
+| ------------------------ | ------------- | ------------------------------------------------ |
+| `db`                     | excluded      | Positive match against an empty tag set is false |
+| `*`                      | excluded      | The bare wildcard requires at least one tag      |
+| `db or unit`             | excluded      | Both branches are false against an empty tag set |
+| `not flaky`              | included      | Negation against an empty tag set is true        |
+| `not flaky and not slow` | included      | Both negations are true against an empty tag set |
+| `db or not flaky`        | included      | The negated branch is true                       |
+
+For example, `--experimental-test-tag-filter='not flaky'` runs every test
+that is not tagged `flaky`, including all untagged tests.
+
+#### Composing multiple filters
+
+[`--experimental-test-tag-filter`][] may be specified more than once on the
+command line. Multiple expressions compose by AND—a test must satisfy
+every expression to run. The same applies to passing an array to
+`testTagFilters` on [`run()`][]. The tag filter is also AND'd with
+[`--test-name-pattern`][], [`--test-skip-pattern`][], and `.only`
+filtering.
+
+#### Reading tags from inside a test
 
 The [`TestContext`][] object exposes the test's tags as a frozen array
 through [`context.tags`][], so tests can branch on their own metadata.
 
-### Errors
+#### Errors
 
 A tag value that violates the validation rules above throws
 `ERR_INVALID_ARG_VALUE` at the registration site, before any test runs.
-A non-array `tags` value throws `ERR_INVALID_ARG_TYPE`.
+A non-array `tags` value throws `ERR_INVALID_ARG_TYPE`. A malformed
+filter expression on the CLI causes the test runner to exit with a
+non-zero status before running any test files.
 
 ## Extraneous asynchronous activity
 
@@ -830,7 +882,7 @@ test runner functionality:
 
 * `--test` - Prevented to avoid recursive test execution
 * `--experimental-test-coverage` - Managed by the test runner
-* `--experimental-test-tag-filter` - Filter values are validated by the parent
+* `--experimental-test-tag-filter` - Filter expressions are validated by the parent
   process and re-emitted to child processes
 * `--watch` - Watch mode is handled at the parent level
 * `--experimental-default-config-file` - Config file loading is handled by the parent
@@ -1746,10 +1798,11 @@ changes:
     For each test that is executed, any corresponding test hooks, such as
     `beforeEach()`, are also run.
     **Default:** `undefined`.
-  * `testTagFilters` {string|string\[]} A tag name, or an array of tag names,
-    used to filter tests by their declared tags. Tests must contain every
-    listed tag to run. Equivalent to passing [`--experimental-test-tag-filter`][]
-    on the command line. See [Test tags][]. **Default:** `undefined`.
+  * `testTagFilters` {string|string\[]} A boolean expression, or an array of
+    boolean expressions, used to filter tests by their declared tags.
+    Multiple expressions compose by AND. Equivalent to passing
+    [`--experimental-test-tag-filter`][] on the command line. See
+    [Test tags][]. **Default:** `undefined`.
   * `timeout` {number} A number of milliseconds the test execution will
     fail after.
     If unspecified, subtests inherit this value from their parent.
diff --git a/doc/node.1 b/doc/node.1
index 1098bcff047f..4af724f56419 100644
--- a/doc/node.1
+++ b/doc/node.1
@@ -814,14 +814,18 @@ collecting code coverage from tests for more details.
 Enable module mocking in the test runner.
 This feature requires \fB--allow-worker\fR if used with the Permission Model.
 .
-.It Fl -experimental-test-tag-filter Ns = Ns Ar <tag>
-Run only tests whose tag set contains \fB<tag>\fR. Tests declare tags via the
-\fBtags\fR option on \fBtest()\fR, \fBit()\fR, \fBsuite()\fR, or \fBdescribe()\fR; tags
-inherit from suites to nested tests by union. Filtering is
-case-insensitive.
-The flag may be specified more than once; tests must contain \fBevery\fR
-filter value to run. See Test tags for details on declaring and
-inheriting tags.
+.It Fl -experimental-test-tag-filter Ns = Ns Ar '<expr>'
+Run only tests that match the provided boolean tag-filter expression. Tests
+declare tags via the \fBtags\fR option on \fBtest()\fR, \fBit()\fR, \fBsuite()\fR, or
+\fBdescribe()\fR. Tags inherit from suites to nested tests by union.
+The expression supports boolean operators (\fBand\fR/\fB&&\fR, \fBor\fR/\fB||\fR,
+\fBnot\fR/\fB!\fR), parentheses for grouping, and \fB*\fR wildcards inside identifiers.
+Standard precedence applies: \fBnot\fR binds tighter than \fBand\fR, which binds
+tighter than \fBor\fR. See Test tags for the full grammar and behavior.
+The flag may be specified more than once; multiple expressions are combined
+with AND, so a test must satisfy every expression to run.
+A malformed expression causes the test runner to exit with a non-zero status
+before running any tests.
 .
 .It Fl -experimental-vfs
 Enable the experimental \fBnode:vfs\fR module.
diff --git a/lib/internal/test_runner/runner.js b/lib/internal/test_runner/runner.js
index 548ed006e152..49ef9cb465b4 100644
--- a/lib/internal/test_runner/runner.js
+++ b/lib/internal/test_runner/runner.js
@@ -12,6 +12,7 @@ const {
   ArrayPrototypePush,
   ArrayPrototypePushApply,
   ArrayPrototypeShift,
+  ArrayPrototypeSlice,
   ArrayPrototypeSome,
   ArrayPrototypeSort,
   MathMax,
@@ -93,7 +94,7 @@ const {
   parseCommandLine,
 } = require('internal/test_runner/utils');
 const {
-  validateAndCanonicalizeTagFilter,
+  parseTagFilterExpression,
 } = require('internal/test_runner/tag_filter');
 const { Glob } = require('internal/fs/glob');
 const { once } = require('events');
@@ -182,7 +183,7 @@ function getRunArgs(path, { forceExit,
                             inspectPort,
                             testNamePatterns,
                             testSkipPatterns,
-                            testTagFilters,
+                            testTagFilterExpressions,
                             only,
                             hasFiles,
                             testFiles,
@@ -224,8 +225,8 @@ function getRunArgs(path, { forceExit,
   if (testSkipPatterns != null) {
     ArrayPrototypeForEach(testSkipPatterns, (pattern) => ArrayPrototypePush(runArgs, `--test-skip-pattern=${pattern}`));
   }
-  if (testTagFilters != null) {
-    ArrayPrototypeForEach(testTagFilters, (value) => ArrayPrototypePush(runArgs, `--experimental-test-tag-filter=${value}`));
+  if (testTagFilterExpressions != null) {
+    ArrayPrototypeForEach(testTagFilterExpressions, (expr) => ArrayPrototypePush(runArgs, `--experimental-test-tag-filter=${expr}`));
   }
   if (only === true) {
     ArrayPrototypePush(runArgs, '--test-only');
@@ -872,19 +873,37 @@ function run(options = kEmptyObject) {
     });
   }
 
+  // The public contract of testTagFilters is `string | string[]`. The
+  // parseCommandLine bootstrap path piggybacks the already-parsed AST array
+  // on the same field, identifiable by the sibling testTagFilterExpressions
+  // field which only that path sets. When that marker is present and the
+  // first element isn't a string, treat the array as ASTs and skip the
+  // public validation loop. Otherwise validate every element as a string,
+  // so any non-string input throws ERR_INVALID_ARG_TYPE with the offending
+  // index regardless of position.
+  let testTagFilterExpressions = null;
   if (testTagFilters != null) {
     if (!ArrayIsArray(testTagFilters)) {
       testTagFilters = [testTagFilters];
     }
     if (testTagFilters.length === 0) {
       testTagFilters = null;
+    } else if (options.testTagFilterExpressions != null &&
+               typeof testTagFilters[0] !== 'string') {
+      // Internal bootstrap: trust the AST array as already-parsed.
     } else {
       emitExperimentalWarning('Test tags');
-      testTagFilters = ArrayPrototypeMap(testTagFilters, (value, i) => (
-        validateAndCanonicalizeTagFilter(value, `options.testTagFilters[${i}]`)
-      ));
+      testTagFilterExpressions = ArrayPrototypeSlice(testTagFilters);
+      testTagFilters = ArrayPrototypeMap(testTagFilters, (value, i) => {
+        const name = `options.testTagFilters[${i}]`;
+        if (typeof value !== 'string') {
+          throw new ERR_INVALID_ARG_TYPE(name, 'string', value);
+        }
+        return parseTagFilterExpression(value, name);
+      });
     }
   }
+  testTagFilterExpressions ??= options.testTagFilterExpressions;
 
   validateOneOf(isolation, 'options.isolation', ['process', 'none']);
   validateBoolean(coverage, 'options.coverage');
@@ -986,7 +1005,7 @@ function run(options = kEmptyObject) {
     inspectPort,
     testNamePatterns,
     testSkipPatterns,
-    testTagFilters,
+    testTagFilterExpressions,
     hasFiles: files != null,
     globPatterns,
     only,
diff --git a/lib/internal/test_runner/tag_filter.js b/lib/internal/test_runner/tag_filter.js
index 35dc2647a2aa..0151abf31cc7 100644
--- a/lib/internal/test_runner/tag_filter.js
+++ b/lib/internal/test_runner/tag_filter.js
@@ -2,8 +2,14 @@
 const {
   ArrayPrototypePush,
   ObjectFreeze,
+  RegExp,
+  RegExpPrototypeExec,
   SafeSet,
+  StringPrototypeCharCodeAt,
+  StringPrototypeSlice,
+  StringPrototypeSplit,
   StringPrototypeToLowerCase,
+  StringPrototypeTrim,
 } = primordials;
 
 const {
@@ -19,14 +25,68 @@ const {
   validateString,
 } = require('internal/validators');
 
+const kCharAmpersand = 0x26;
+const kCharBackslash = 0x5C;
+const kCharCarriageReturn = 0x0D;
+const kCharCaret = 0x5E;
+const kCharDollar = 0x24;
+const kCharDot = 0x2E;
+const kCharExclaim = 0x21;
+const kCharFormFeed = 0x0C;
+const kCharLBrace = 0x7B;
+const kCharLBracket = 0x5B;
+const kCharLineFeed = 0x0A;
+const kCharLParen = 0x28;
+const kCharPipe = 0x7C;
+const kCharPlus = 0x2B;
+const kCharQuestion = 0x3F;
+const kCharRBrace = 0x7D;
+const kCharRBracket = 0x5D;
+const kCharRParen = 0x29;
+const kCharSpace = 0x20;
+const kCharStar = 0x2A;
+const kCharTab = 0x09;
+const kCharVerticalTab = 0x0B;
+
+// Single `&` and `|` are allowed here: standalone they have no operator
+// meaning, only the doubled forms `&&` and `||` do.
+const kTagForbiddenChars = new SafeSet([
+  kCharTab, kCharLineFeed, kCharVerticalTab, kCharFormFeed, kCharCarriageReturn, kCharSpace,
+  kCharAmpersand, kCharExclaim, kCharLParen, kCharPipe, kCharRParen, kCharStar,
+]);
+
+const kReservedWords = new SafeSet(['and', 'or', 'not']);
+
+/**
+ * Frozen, shared empty array used as the canonical "no tags" value for
+ * tests that don't declare their own and have no tagged ancestors.
+ * Sharing one frozen instance avoids per-test allocation.
+ * @type {readonly string[]}
+ */
 const kEmptyTagArray = ObjectFreeze([]);
 
+function isWhitespace(ch) {
+  return ch === kCharTab || ch === kCharLineFeed || ch === kCharVerticalTab ||
+         ch === kCharFormFeed || ch === kCharCarriageReturn || ch === kCharSpace;
+}
+
+// `*` is intentionally not a break char: it's allowed inside an identifier
+// and becomes a wildcard.
+function isIdentBreak(ch) {
+  return isWhitespace(ch) ||
+         ch === kCharAmpersand || ch === kCharPipe ||
+         ch === kCharExclaim || ch === kCharLParen || ch === kCharRParen;
+}
+
 /**
  * Validate and canonicalize a `tags` option value supplied to `test()`,
  * `it()`, `suite()`, or `describe()`.
  *
- * Each tag must be a non-empty string. Tags are canonicalized to lowercase
- * and deduplicated, preserving first-seen declaration order.
+ * Each tag must be a non-empty string that contains no whitespace, no
+ * operator characters (`& | ! ( ) *`), and is not the reserved word
+ * `'and'`, `'or'`, or `'not'` in any casing. Tags are canonicalized to
+ * lowercase and deduplicated on the lowercased form, preserving the
+ * first-seen declaration order.
  *
  * Calling this with a non-empty array also emits the one-shot
  * `ExperimentalWarning` for the test-tags feature.
@@ -37,7 +97,8 @@ const kEmptyTagArray = ObjectFreeze([]);
  *   Returns an empty array when `tags` is `[]`.
  * @throws {ERR_INVALID_ARG_TYPE} If `tags` is not an array, or any element
  *   is not a string.
- * @throws {ERR_INVALID_ARG_VALUE} If any element is empty.
+ * @throws {ERR_INVALID_ARG_VALUE} If any element is empty, contains a
+ *   forbidden character, or is a reserved word in any casing.
  */
 function validateAndCanonicalizeTagValues(tags, optName) {
   validateArray(tags, optName);
@@ -55,7 +116,34 @@ function validateAndCanonicalizeTagValues(tags, optName) {
     const tag = tags[i];
     const elemName = `${optName}[${i}]`;
 
-    const lower = validateAndCanonicalizeTagFilter(tag, elemName);
+    validateString(tag, elemName);
+
+    if (tag.length === 0) {
+      throw new ERR_INVALID_ARG_VALUE(elemName, tag, 'must not be empty');
+    }
+
+    for (let j = 0; j < tag.length; j++) {
+      const ch = StringPrototypeCharCodeAt(tag, j);
+      if (kTagForbiddenChars.has(ch)) {
+        throw new ERR_INVALID_ARG_VALUE(
+          elemName,
+          tag,
+          'contains a forbidden character. Tags must not contain whitespace, ' +
+          'operator characters (&, |, !, (, ), *), or be the reserved words ' +
+          '\'and\', \'or\', or \'not\'',
+        );
+      }
+    }
+
+    const lower = StringPrototypeToLowerCase(tag);
+
+    if (kReservedWords.has(lower)) {
+      throw new ERR_INVALID_ARG_VALUE(
+        elemName,
+        tag,
+        'must not be the reserved word \'and\', \'or\', or \'not\'',
+      );
+    }
 
     if (!seen.has(lower)) {
       seen.add(lower);
@@ -66,43 +154,341 @@ function validateAndCanonicalizeTagValues(tags, optName) {
   return ObjectFreeze(result);
 }
 
+// ---------------------------------------------------------------------------
+// Lexer
+// ---------------------------------------------------------------------------
+
+// Token types
+const T_AND = 'AND';
+const T_OR = 'OR';
+const T_NOT = 'NOT';
+const T_LPAREN = 'LPAREN';
+const T_RPAREN = 'RPAREN';
+const T_IDENT = 'IDENT';
+const T_EOF = 'EOF';
+
+function lex(expr, name) {
+  const tokens = [];
+  let i = 0;
+  const len = expr.length;
+
+  while (i < len) {
+    const ch = StringPrototypeCharCodeAt(expr, i);
+
+    if (isWhitespace(ch)) {
+      i++;
+      continue;
+    }
+
+    if (ch === kCharAmpersand) {
+      if (i + 1 < len && StringPrototypeCharCodeAt(expr, i + 1) === kCharAmpersand) {
+        ArrayPrototypePush(tokens, { __proto__: null, type: T_AND, pos: i });
+        i += 2;
+      } else {
+        throw new ERR_INVALID_ARG_VALUE(
+          name, expr,
+          `unexpected '&' at position ${i}; use '&&' or 'and'`,
+        );
+      }
+      continue;
+    }
+
+    if (ch === kCharPipe) {
+      if (i + 1 < len && StringPrototypeCharCodeAt(expr, i + 1) === kCharPipe) {
+        ArrayPrototypePush(tokens, { __proto__: null, type: T_OR, pos: i });
+        i += 2;
+      } else {
+        throw new ERR_INVALID_ARG_VALUE(
+          name, expr,
+          `unexpected '|' at position ${i}; use '||' or 'or'`,
+        );
+      }
+      continue;
+    }
+
+    if (ch === kCharExclaim) {
+      ArrayPrototypePush(tokens, { __proto__: null, type: T_NOT, pos: i });
+      i++;
+      continue;
+    }
+
+    if (ch === kCharLParen) {
+      ArrayPrototypePush(tokens, { __proto__: null, type: T_LPAREN, pos: i });
+      i++;
+      continue;
+    }
+
+    if (ch === kCharRParen) {
+      ArrayPrototypePush(tokens, { __proto__: null, type: T_RPAREN, pos: i });
+      i++;
+      continue;
+    }
+
+    const start = i;
+    while (i < len && !isIdentBreak(StringPrototypeCharCodeAt(expr, i))) {
+      i++;
+    }
+    const ident = StringPrototypeSlice(expr, start, i);
+    const lower = StringPrototypeToLowerCase(ident);
+
+    if (lower === 'and') {
+      ArrayPrototypePush(tokens, { __proto__: null, type: T_AND, pos: start });
+    } else if (lower === 'or') {
+      ArrayPrototypePush(tokens, { __proto__: null, type: T_OR, pos: start });
+    } else if (lower === 'not') {
+      ArrayPrototypePush(tokens, { __proto__: null, type: T_NOT, pos: start });
+    } else {
+      ArrayPrototypePush(tokens, { __proto__: null, type: T_IDENT, value: ident, pos: start });
+    }
+  }
+
+  ArrayPrototypePush(tokens, { __proto__: null, type: T_EOF, pos: len });
+  return tokens;
+}
+
+// ---------------------------------------------------------------------------
+// Regex escaping for wildcard tags
+// ---------------------------------------------------------------------------
+
+// `*` is the only metacharacter intentionally not escaped: the caller
+// handles it as a wildcard.
+function escapeForRegExp(str) {
+  let result = '';
+  for (let i = 0; i < str.length; i++) {
+    const ch = StringPrototypeCharCodeAt(str, i);
+    if (
+      ch === kCharLBracket || ch === kCharRBracket ||
+      ch === kCharLParen || ch === kCharRParen ||
+      ch === kCharLBrace || ch === kCharRBrace ||
+      ch === kCharCaret || ch === kCharDollar ||
+      ch === kCharDot || ch === kCharPlus ||
+      ch === kCharQuestion || ch === kCharBackslash ||
+      ch === kCharPipe
+    ) {
+      result += '\\';
+    }
+    result += StringPrototypeSlice(str, i, i + 1);
+  }
+  return result;
+}
+
+function buildWildcardRegex(ident) {
+  // Lowercase the source first and drop the /i flag, so wildcard matching
+  // uses the same casing semantics as literal matching (which lowercases the
+  // tag value at validation time). Using /i would diverge for non-ASCII
+  // characters whose String.prototype.toLowerCase() output differs from
+  // RegExp /i case folding (e.g. Turkish I-with-dot U+0130).
+  const parts = StringPrototypeSplit(StringPrototypeToLowerCase(ident), '*');
+  let pattern = '^';
+  for (let i = 0; i < parts.length; i++) {
+    if (i > 0) {
+      pattern += '.*';
+    }
+    pattern += escapeForRegExp(parts[i]);
+  }
+  pattern += '$';
+  return new RegExp(pattern);
+}
+
+function makeTagNode(ident) {
+  for (let i = 0; i < ident.length; i++) {
+    if (StringPrototypeCharCodeAt(ident, i) === kCharStar) {
+      return { __proto__: null, type: 'wildcard', re: buildWildcardRegex(ident) };
+    }
+  }
+  return { __proto__: null, type: 'tag', value: StringPrototypeToLowerCase(ident) };
+}
+
+// ---------------------------------------------------------------------------
+// Parser - recursive descent
+// Precedence: not > and > or  (standard Boolean)
+// ---------------------------------------------------------------------------
+
 /**
- * Validate and canonicalize a single tag-filter string supplied via
- * `--experimental-test-tag-filter` or `testTagFilters`.
+ * Parse a tag filter expression string into an AST suitable for
+ * `evaluateTagFilters`.
  *
- * Filters are literal tag names: a test passes the filter when its tag set
- * contains the lowercased filter value. Multi-occurrence composes by AND
- * at the call site (see `evaluateTagFilters`).
- * @param {unknown} value - The supplied filter string.
- * @param {string} name - Argument name embedded in thrown error messages.
- * @returns {string} The lowercased filter value.
- * @throws {ERR_INVALID_ARG_TYPE} If `value` is not a string.
- * @throws {ERR_INVALID_ARG_VALUE} If `value` is empty.
+ * Supported syntax:
+ *   - Identifiers: any non-whitespace, non-operator characters; case-
+ *     insensitive when matched. A `*` inside an identifier becomes a
+ *     wildcard that matches any sequence of characters; a bare `*`
+ *     matches any non-empty tag.
+ *   - Boolean operators: `and`/`&&`, `or`/`||`, `not`/`!`, with the
+ *     standard precedence `not > and > or` and left-associative binary
+ *     operators. Word forms must be whitespace-separated; punctuation
+ *     forms do not.
+ *   - Parentheses for grouping.
+ * @param {string} expr - The expression to parse.
+ * @param {string} name - Option name to embed in thrown error messages
+ *   (typically `'--experimental-test-tag-filter[<i>]'` or
+ *   `'options.testTagFilters[<i>]'`).
+ * @returns {object} An opaque AST node. The shape is internal; pass it
+ *   only to `evaluateTagFilters`.
+ * @throws {ERR_INVALID_ARG_TYPE} If `expr` is not a string.
+ * @throws {ERR_INVALID_ARG_VALUE} If `expr` is empty, contains only
+ *   whitespace, or has a syntax error (unbalanced parentheses, dangling
+ *   operator, adjacent identifiers, etc.). The error message includes
+ *   the offending position.
  */
-function validateAndCanonicalizeTagFilter(value, name) {
-  validateString(value, name);
+function parseTagFilterExpression(expr, name) {
+  validateString(expr, name);
+
+  if (StringPrototypeTrim(expr).length === 0) {
+    throw new ERR_INVALID_ARG_VALUE(name, expr, 'must not be empty');
+  }
+
+  const tokens = lex(expr, name);
+  let pos = 0;
+
+  function peek() {
+    return tokens[pos];
+  }
+
+  function consume() {
+    return tokens[pos++];
+  }
+
+  function parseExpr() {
+    return parseOr();
+  }
+
+  function parseOr() {
+    let left = parseAnd();
+    while (peek().type === T_OR) {
+      consume();
+      const right = parseAnd();
+      left = { __proto__: null, type: 'or', left, right };
+    }
+    return left;
+  }
 
-  if (value.length === 0) {
-    throw new ERR_INVALID_ARG_VALUE(name, value, 'must not be empty');
+  function parseAnd() {
+    let left = parseNot();
+    while (peek().type === T_AND) {
+      consume();
+      const right = parseNot();
+      left = { __proto__: null, type: 'and', left, right };
+    }
+    return left;
   }
 
-  return StringPrototypeToLowerCase(value);
+  function parseNot() {
+    if (peek().type === T_NOT) {
+      const { pos: notPos } = consume();
+      if (peek().type === T_EOF) {
+        throw new ERR_INVALID_ARG_VALUE(
+          name, expr,
+          `expected operand after 'not' at position ${notPos}`,
+        );
+      }
+      const operand = parseNot();
+      return { __proto__: null, type: 'not', operand };
+    }
+
+    if (peek().type === T_LPAREN) {
+      const { pos: lPos } = consume();
+      if (peek().type === T_EOF) {
+        throw new ERR_INVALID_ARG_VALUE(
+          name, expr,
+          `unmatched '(' at position ${lPos}`,
+        );
+      }
+      const inner = parseExpr();
+      if (peek().type !== T_RPAREN) {
+        throw new ERR_INVALID_ARG_VALUE(
+          name, expr,
+          `expected ')' at position ${peek().pos}`,
+        );
+      }
+      consume();
+      return inner;
+    }
+
+    if (peek().type === T_IDENT) {
+      const { value } = consume();
+      return makeTagNode(value);
+    }
+
+    const tok = peek();
+    throw new ERR_INVALID_ARG_VALUE(
+      name, expr,
+      `unexpected token '${tok.type}' at position ${tok.pos}`,
+    );
+  }
+
+  const ast = parseExpr();
+
+  if (peek().type !== T_EOF) {
+    const tok = peek();
+    throw new ERR_INVALID_ARG_VALUE(
+      name, expr,
+      `unexpected token at position ${tok.pos}`,
+    );
+  }
+
+  return ast;
 }
 
+// ---------------------------------------------------------------------------
+// Evaluator
+// ---------------------------------------------------------------------------
+
 /**
- * Evaluate a list of tag filters against a test's tag set.
+ * Evaluate a tag filter AST against a set of test tags.
+ *
+ * Untagged tests have an empty SafeSet. The semantics are:
+ *   - An include expression (tag/wildcard/and/or) evaluates false for empty set.
+ *   - 'not X' evaluates true when X is false (so untagged tests pass 'not X').
+ * @param {object} ast - AST node from parseTagFilterExpression.
+ * @param {SafeSet} tags - Lowercased canonical tags for the test.
+ * @returns {boolean}
+ */
+function evaluateTagFilter(ast, tags) {
+  const { type } = ast;
+
+  if (type === 'or') {
+    return evaluateTagFilter(ast.left, tags) || evaluateTagFilter(ast.right, tags);
+  }
+
+  if (type === 'and') {
+    return evaluateTagFilter(ast.left, tags) && evaluateTagFilter(ast.right, tags);
+  }
+
+  if (type === 'not') {
+    return !evaluateTagFilter(ast.operand, tags);
+  }
+
+  if (type === 'tag') {
+    return tags.has(ast.value);
+  }
+
+  // type === 'wildcard'
+  let matched = false;
+  tags.forEach((tag) => {
+    if (!matched && RegExpPrototypeExec(ast.re, tag) !== null) {
+      matched = true;
+    }
+  });
+  return matched;
+}
+
+/**
+ * Evaluate one or more tag filter ASTs against a test's tag set.
+ *
+ * Multiple ASTs compose by AND: a test passes only when every AST
+ * evaluates true for it. An empty `asts` array always passes.
  *
- * Multiple filters compose by AND: a test passes only when every filter is
- * present in its tag set. An empty `filters` array always passes. Untagged
- * tests have an empty tag set and so are excluded under any non-empty
- * filter.
- * @param {string[]} filters - Lowercased canonical filter values.
- * @param {SafeSet<string>} tags - The test's lowercased canonical tag set.
+ * Untagged tests (an empty `tags` set) fail any include expression
+ * (`tag`, `wildcard`, `and`, `or`) and pass `not X`, so excluding tags
+ * does not accidentally remove untagged tests.
+ * @param {object[]} asts - ASTs returned by `parseTagFilterExpression`.
+ * @param {SafeSet<string>} tags - The test's lowercased canonical tag
+ *   set (use `Set` in non-internal contexts; both work).
  * @returns {boolean} `true` if the test should run.
  */
-function evaluateTagFilters(filters, tags) {
-  for (let i = 0; i < filters.length; i++) {
-    if (!tags.has(filters[i])) {
+function evaluateTagFilters(asts, tags) {
+  for (let i = 0; i < asts.length; i++) {
+    if (!evaluateTagFilter(asts[i], tags)) {
       return false;
     }
   }
@@ -112,6 +498,6 @@ function evaluateTagFilters(filters, tags) {
 module.exports = {
   evaluateTagFilters,
   kEmptyTagArray,
-  validateAndCanonicalizeTagFilter,
+  parseTagFilterExpression,
   validateAndCanonicalizeTagValues,
 };
diff --git a/lib/internal/test_runner/utils.js b/lib/internal/test_runner/utils.js
index 982fc6ef7bfe..38b54c31685c 100644
--- a/lib/internal/test_runner/utils.js
+++ b/lib/internal/test_runner/utils.js
@@ -30,7 +30,7 @@ const {
 } = primordials;
 
 const {
-  validateAndCanonicalizeTagFilter,
+  parseTagFilterExpression,
 } = require('internal/test_runner/tag_filter');
 
 const { AsyncResource } = require('async_hooks');
@@ -273,6 +273,7 @@ function parseCommandLine() {
   let testNamePatterns = mapPatternFlagToRegExArray('--test-name-pattern');
   let testSkipPatterns = mapPatternFlagToRegExArray('--test-skip-pattern');
   let testTagFilters = null;
+  let testTagFilterExpressions = null;
 
   if (isChildProcessV8) {
     kBuiltinReporters.set('v8-serializer', 'internal/test_runner/reporter/v8-serializer');
@@ -308,13 +309,14 @@ function parseCommandLine() {
     const tagFilterFlag = getOptionValue('--experimental-test-tag-filter');
     if (tagFilterFlag?.length > 0) {
       emitExperimentalWarning('Test tags');
-      // File wrappers are exempt from tag filtering, so holding the filters
-      // in the parent is safe under any isolation mode; under
-      // isolation='process' the canonical values are re-emitted to the
-      // child processes, which apply the filter themselves.
+      // File wrappers are exempt from tag filtering, so holding the parsed
+      // ASTs in the parent is safe under any isolation mode; under
+      // isolation='process' the source expressions are re-emitted to the
+      // child processes, which re-parse and apply the filter themselves.
+      testTagFilterExpressions = tagFilterFlag;
       testTagFilters = ArrayPrototypeMap(
         tagFilterFlag,
-        (value, i) => validateAndCanonicalizeTagFilter(value, `--experimental-test-tag-filter[${i}]`),
+        (expr, i) => parseTagFilterExpression(expr, `--experimental-test-tag-filter[${i}]`),
       );
     }
 
@@ -359,9 +361,10 @@ function parseCommandLine() {
     const tagFilterFlag = getOptionValue('--experimental-test-tag-filter');
     if (tagFilterFlag?.length > 0) {
       emitExperimentalWarning('Test tags');
+      testTagFilterExpressions = tagFilterFlag;
       testTagFilters = ArrayPrototypeMap(
         tagFilterFlag,
-        (value, i) => validateAndCanonicalizeTagFilter(value, `--experimental-test-tag-filter[${i}]`),
+        (expr, i) => parseTagFilterExpression(expr, `--experimental-test-tag-filter[${i}]`),
       );
     }
   }
@@ -426,6 +429,7 @@ function parseCommandLine() {
     sourceMaps,
     testNamePatterns,
     testSkipPatterns,
+    testTagFilterExpressions,
     testTagFilters,
     timeout,
     updateSnapshots,
diff --git a/test/parallel/test-runner-tag-filter-cli.mjs b/test/parallel/test-runner-tag-filter-cli.mjs
index 13717d34b3ed..e7a1cd2d1d5f 100644
--- a/test/parallel/test-runner-tag-filter-cli.mjs
+++ b/test/parallel/test-runner-tag-filter-cli.mjs
@@ -62,32 +62,55 @@ test('untagged parent runs only the matching tagged child', () => {
   assert.doesNotMatch(stdout, /plain sibling/);
 });
 
+test('not X also includes untagged tests', () => {
+  const { status, stdout } = run(['--experimental-test-tag-filter=not flaky']);
+  assert.strictEqual(status, 0);
+  pass(stdout, 8);
+  assert.match(stdout, /ok \d+ - untagged/);
+  assert.doesNotMatch(stdout, /db flaky/);
+  assert.doesNotMatch(stdout, /^ok \d+ - only flaky/m);
+});
+
 test('repeated --experimental-test-tag-filter ANDs together', () => {
-  // db AND integration: only "db plus integration" satisfies both.
   const { status, stdout } = run([
     '--experimental-test-tag-filter=db',
-    '--experimental-test-tag-filter=integration',
+    '--experimental-test-tag-filter=not flaky',
   ]);
   assert.strictEqual(status, 0);
-  pass(stdout, 1);
+  pass(stdout, 2);
+  assert.match(stdout, /ok \d+ - db only/);
   assert.match(stdout, /ok \d+ - db plus integration/);
-  assert.doesNotMatch(stdout, /^ok \d+ - db only/m);
-  assert.doesNotMatch(stdout, /^ok \d+ - db flaky/m);
+  assert.doesNotMatch(stdout, /db flaky/);
 });
 
-test('untagged tests are excluded under any positive filter', () => {
-  const { status, stdout } = run(['--experimental-test-tag-filter=db']);
+test('bare * matches any tagged test, excludes untagged', () => {
+  const { status, stdout } = run(['--experimental-test-tag-filter=*']);
   assert.strictEqual(status, 0);
+  pass(stdout, 8);
   assert.doesNotMatch(stdout, /^ok \d+ - untagged/m);
 });
 
+test('wildcard prefix: db* matches db, db:postgres, etc.', () => {
+  const { status, stdout } = run(['--experimental-test-tag-filter=db*']);
+  assert.strictEqual(status, 0);
+  pass(stdout, 4);
+  assert.match(stdout, /db wildcard match/);
+});
+
+test('boolean composition: unit && !slow', () => {
+  const { status, stdout } = run(['--experimental-test-tag-filter=unit && !slow']);
+  assert.strictEqual(status, 0);
+  pass(stdout, 1);
+  assert.match(stdout, /ok \d+ - unit only/);
+});
+
 test('isolation=none produces identical filtered set', () => {
-  const proc = run(['--experimental-test-tag-filter=db']);
-  const none = run(['--experimental-test-tag-filter=db'], ['--test-isolation=none']);
+  const proc = run(['--experimental-test-tag-filter=unit && !slow']);
+  const none = run(['--experimental-test-tag-filter=unit && !slow'], ['--test-isolation=none']);
   assert.strictEqual(proc.status, 0);
   assert.strictEqual(none.status, 0);
-  pass(proc.stdout, 3);
-  pass(none.stdout, 3);
+  pass(proc.stdout, 1);
+  pass(none.stdout, 1);
 });
 
 test('combined with --test-skip-pattern (pure AND)', () => {
@@ -101,8 +124,44 @@ test('combined with --test-skip-pattern (pure AND)', () => {
   assert.doesNotMatch(stdout, /db flaky/);
 });
 
+test('malformed expression: unbalanced parenthesis errors at startup', () => {
+  const { status, stderr, stdout } = run(['--experimental-test-tag-filter=(a']);
+  assert.notStrictEqual(status, 0);
+  // Match the full sentinel error line so noise elsewhere in stderr can't
+  // satisfy the assertion via interleaved substrings.
+  assert.match(
+    stderr,
+    /^TypeError \[ERR_INVALID_ARG_VALUE\]: The argument '--experimental-test-tag-filter\[0\]' expected '\)' at position \d+/m,
+  );
+  // No file should have been spawned.
+  assert.doesNotMatch(stdout, /^ok 1 -/m);
+});
+
+test('malformed expression: dangling operator errors at startup', () => {
+  const { status, stderr } = run(['--experimental-test-tag-filter=a and']);
+  assert.notStrictEqual(status, 0);
+  assert.match(
+    stderr,
+    /^TypeError \[ERR_INVALID_ARG_VALUE\]: The argument '--experimental-test-tag-filter\[0\]' unexpected token 'EOF' at position \d+/m,
+  );
+});
+
 test('empty --experimental-test-tag-filter= is rejected by argv parser', () => {
   const { status, stderr } = run(['--experimental-test-tag-filter=']);
   assert.notStrictEqual(status, 0);
   assert.match(stderr, /requires an argument/);
 });
+
+test('reserved word as tag value errors at registration', () => {
+  const child = spawnSync(process.execPath, [
+    '-e',
+    "require('node:test').test('x', { tags: ['and'] }, () => {});",
+  ]);
+  assert.notStrictEqual(child.status, 0);
+  // Match the full sentinel error line so noise elsewhere in stderr can't
+  // satisfy the assertion via interleaved substrings.
+  assert.match(
+    child.stderr.toString(),
+    /^TypeError \[ERR_INVALID_ARG_VALUE\]: The property 'options\.tags\[0\]' must not be the reserved word/m,
+  );
+});
diff --git a/test/parallel/test-runner-tag-filter-parser.mjs b/test/parallel/test-runner-tag-filter-parser.mjs
new file mode 100644
index 000000000000..0a9ab93dc98c
--- /dev/null
+++ b/test/parallel/test-runner-tag-filter-parser.mjs
@@ -0,0 +1,257 @@
+// Flags: --expose-internals
+
+import '../common/index.mjs';
+import assert from 'node:assert';
+import { test } from 'node:test';
+import tagFilter from 'internal/test_runner/tag_filter';
+
+const { evaluateTagFilters, parseTagFilterExpression } = tagFilter;
+
+function tagSet(...tags) {
+  return new Set(tags);
+}
+
+function matches(expr, ...tags) {
+  return evaluateTagFilters([parseTagFilterExpression(expr, 'expr')], tagSet(...tags));
+}
+
+test('single identifier', () => {
+  assert.strictEqual(matches('db', 'db'), true);
+  assert.strictEqual(matches('db', 'other'), false);
+  assert.strictEqual(matches('db'), false);
+});
+
+test('case-insensitive match', () => {
+  // The evaluator expects an already-lowercased tag set, so 'DB' in the set
+  // must not match 'db' in the filter.
+  assert.strictEqual(matches('DB', 'db'), true);
+  assert.strictEqual(matches('db', 'DB'), false);
+});
+
+test('and / && have higher precedence than or / ||', () => {
+  for (const expr of ['a or b and c', 'a || b && c']) {
+    assert.strictEqual(matches(expr, 'a'), true);
+    assert.strictEqual(matches(expr, 'b'), false);
+    assert.strictEqual(matches(expr, 'c'), false);
+    assert.strictEqual(matches(expr, 'a', 'b'), true);
+    assert.strictEqual(matches(expr, 'a', 'c'), true);
+    assert.strictEqual(matches(expr, 'b', 'c'), true);
+    assert.strictEqual(matches(expr, 'a', 'b', 'c'), true);
+  }
+});
+
+test('not has higher precedence than and', () => {
+  for (const expr of ['not a and b', '!a && b']) {
+    assert.strictEqual(matches(expr, 'b'), true);
+    assert.strictEqual(matches(expr, 'a', 'b'), false);
+  }
+});
+
+test('not has higher precedence than or', () => {
+  for (const expr of ['not a or b', '!a || b']) {
+    assert.strictEqual(matches(expr), true);
+    assert.strictEqual(matches(expr, 'a'), false);
+    assert.strictEqual(matches(expr, 'b'), true);
+    assert.strictEqual(matches(expr, 'a', 'b'), true);
+  }
+});
+
+test('parentheses override precedence', () => {
+  for (const expr of ['(a or b) and c', '(a || b) && c']) {
+    assert.strictEqual(matches(expr, 'a'), false);
+    assert.strictEqual(matches(expr, 'c'), false);
+    assert.strictEqual(matches(expr, 'a', 'c'), true);
+    assert.strictEqual(matches(expr, 'b', 'c'), true);
+  }
+});
+
+test('double negation', () => {
+  for (const expr of ['not not a', '!!a']) {
+    assert.strictEqual(matches(expr, 'a'), true);
+    assert.strictEqual(matches(expr), false);
+  }
+});
+
+test('mixing word and punctuation forms in one expression', () => {
+  for (const expr of ['unit && not flaky', 'unit and !flaky']) {
+    assert.strictEqual(matches(expr, 'unit'), true);
+    assert.strictEqual(matches(expr, 'unit', 'flaky'), false);
+  }
+});
+
+test('mixed forms inside parentheses, word and punct equivalence', () => {
+  // Each pair below is the same expression in word form and punctuation form.
+  for (const expr of ['a and (b || not c)', 'a && (b or not c)']) {
+    assert.strictEqual(matches(expr, 'a'), true);
+    assert.strictEqual(matches(expr, 'a', 'b'), true);
+    assert.strictEqual(matches(expr, 'a', 'c'), false);
+    assert.strictEqual(matches(expr, 'a', 'b', 'c'), true);
+    assert.strictEqual(matches(expr, 'b'), false);
+  }
+
+  for (const expr of ['(a || b) && !c', '(a or b) and not c']) {
+    assert.strictEqual(matches(expr, 'a'), true);
+    assert.strictEqual(matches(expr, 'b'), true);
+    assert.strictEqual(matches(expr, 'a', 'c'), false);
+    assert.strictEqual(matches(expr, 'c'), false);
+  }
+
+  for (const expr of ['not (a or b) and c', '!(a || b) && c']) {
+    assert.strictEqual(matches(expr, 'c'), true);
+    assert.strictEqual(matches(expr, 'a', 'c'), false);
+    assert.strictEqual(matches(expr, 'b', 'c'), false);
+  }
+
+  for (const expr of ['!(a && b) || c', 'not (a and b) or c']) {
+    assert.strictEqual(matches(expr, 'a'), true);
+    assert.strictEqual(matches(expr, 'a', 'b'), false);
+    assert.strictEqual(matches(expr, 'a', 'b', 'c'), true);
+  }
+});
+
+test('nested parentheses and wildcards mixed with word forms', () => {
+  for (const expr of [
+    '(db* or unit) and not (slow || flaky)',
+    '(db* || unit) && !(slow or flaky)',
+  ]) {
+    assert.strictEqual(matches(expr, 'db'), true);
+    assert.strictEqual(matches(expr, 'db:postgres'), true);
+    assert.strictEqual(matches(expr, 'unit'), true);
+    assert.strictEqual(matches(expr, 'unit', 'slow'), false);
+    assert.strictEqual(matches(expr, 'db', 'flaky'), false);
+    assert.strictEqual(matches(expr, 'mongo'), false);
+  }
+});
+
+test("'notslow' is one identifier, 'not slow' is two tokens", () => {
+  assert.strictEqual(matches('notslow', 'notslow'), true);
+  assert.strictEqual(matches('notslow', 'slow'), false);
+  assert.strictEqual(matches('not slow'), true);
+  assert.strictEqual(matches('not slow', 'slow'), false);
+});
+
+test('punctuation does not need whitespace separation', () => {
+  assert.strictEqual(matches('!a', 'b'), true);
+  assert.strictEqual(matches('!a', 'a'), false);
+  assert.strictEqual(matches('a&&b', 'a', 'b'), true);
+  assert.strictEqual(matches('a||b', 'a'), true);
+});
+
+test('wildcard expands across allowed alphabet', () => {
+  assert.strictEqual(matches('db*', 'db'), true);
+  assert.strictEqual(matches('db*', 'db1'), true);
+  assert.strictEqual(matches('db*', 'db:postgres'), true);
+  assert.strictEqual(matches('db*', 'mongo'), false);
+});
+
+test('bare * matches any tagged test', () => {
+  assert.strictEqual(matches('*', 'anything'), true);
+  assert.strictEqual(matches('*', 'a', 'b'), true);
+  assert.strictEqual(matches('*'), false);
+});
+
+test('wildcard in middle and at start', () => {
+  assert.strictEqual(matches('*db', 'mydb'), true);
+  assert.strictEqual(matches('*db', 'db'), true);
+  assert.strictEqual(matches('*db', 'dbmy'), false);
+  assert.strictEqual(matches('a*z', 'abz'), true);
+  assert.strictEqual(matches('a*z', 'az'), true);
+  assert.strictEqual(matches('a*z', 'abc'), false);
+});
+
+test('regex metacharacters in tags are escaped', () => {
+  // The literal `.` in the filter must match a literal dot only, not any
+  // arbitrary character (which would be the unescaped regex meaning).
+  assert.strictEqual(matches('a.b*', 'a.b'), true);
+  assert.strictEqual(matches('a.b*', 'axb'), false);
+});
+
+test('wildcard case-folding matches literal-tag case-folding for non-ASCII', () => {
+  // Authoring a tag 'İ' (U+0130) goes through String.prototype.toLowerCase
+  // and stores 'i̇' (two code points). Wildcard matching must use the same
+  // fold so authors see consistent behavior across literal and wildcard
+  // filters.
+  const folded = 'İ'.toLowerCase();
+  assert.strictEqual(matches('İ', folded), true);
+  assert.strictEqual(matches('İ*', folded), true);
+  assert.strictEqual(matches('İ*', `${folded}foo`), true);
+  assert.strictEqual(matches('*İ', `foo${folded}`), true);
+});
+
+test('untagged test fails any include expression', () => {
+  for (const expr of ['a', 'a or b', 'a || b', 'a and b', 'a && b', '*']) {
+    assert.strictEqual(matches(expr), false);
+  }
+});
+
+test("'not X' against an untagged test is true", () => {
+  for (const expr of ['not a', '!a']) {
+    assert.strictEqual(matches(expr), true);
+  }
+});
+
+test('multiple filters AND together', () => {
+  const f1 = parseTagFilterExpression('a', 'expr');
+  const f2 = parseTagFilterExpression('not b', 'expr');
+  assert.strictEqual(evaluateTagFilters([f1, f2], tagSet('a')), true);
+  assert.strictEqual(evaluateTagFilters([f1, f2], tagSet('a', 'b')), false);
+  assert.strictEqual(evaluateTagFilters([f1, f2], tagSet('b')), false);
+  assert.strictEqual(evaluateTagFilters([f1, f2], tagSet()), false);
+});
+
+test('empty filter list always passes', () => {
+  assert.strictEqual(evaluateTagFilters([], tagSet()), true);
+  assert.strictEqual(evaluateTagFilters([], tagSet('a')), true);
+});
+
+// --- Malformed expressions -------------------------------------------------
+
+function expectInvalid(expr) {
+  assert.throws(
+    () => parseTagFilterExpression(expr, 'expr'),
+    { code: 'ERR_INVALID_ARG_VALUE' },
+    `expected '${expr}' to be invalid`,
+  );
+}
+
+test('rejects empty / whitespace-only expressions', () => {
+  for (const expr of ['', '   ', '\t\n']) {
+    expectInvalid(expr);
+  }
+});
+
+test('rejects unbalanced parentheses', () => {
+  for (const expr of ['(', '((', '(a', 'a)', '((a)', '(a))']) {
+    expectInvalid(expr);
+  }
+});
+
+test('rejects dangling operators', () => {
+  for (const expr of ['not', 'a and', 'a or', '&& a', '|| a', 'a &&', 'a ||']) {
+    expectInvalid(expr);
+  }
+});
+
+test('rejects two adjacent identifiers', () => {
+  expectInvalid('foo bar');
+});
+
+test('rejects single & and single |', () => {
+  for (const expr of ['a & b', 'a | b']) {
+    expectInvalid(expr);
+  }
+});
+
+test('rejects empty parentheses', () => {
+  expectInvalid('()');
+});
+
+test('rejects non-string expressions', () => {
+  for (const expr of [42, null, undefined, true, [], {}, Symbol('s')]) {
+    assert.throws(
+      () => parseTagFilterExpression(expr, 'expr'),
+      { code: 'ERR_INVALID_ARG_TYPE' },
+      `expected ${String(expr)} to be rejected`,
+    );
+  }
+});
diff --git a/test/parallel/test-runner-tags-events.mjs b/test/parallel/test-runner-tags-events.mjs
index 7d1b35f7349d..fab32cfe92c0 100644
--- a/test/parallel/test-runner-tags-events.mjs
+++ b/test/parallel/test-runner-tags-events.mjs
@@ -101,4 +101,12 @@ describe('tag-bearing event payloads', { concurrency: false }, () => {
     // eslint-disable-next-line no-unused-vars
     for await (const _ of stream);
   });
+
+  it('process isolation forwards --experimental-test-tag-filter to children', async () => {
+    const stream = run({ files: [fixture], testTagFilters: ['not nonexistent'] });
+    stream.on('test:fail', common.mustNotCall());
+    stream.on('test:pass', common.mustCall(13));
+    // eslint-disable-next-line no-unused-vars
+    for await (const _ of stream);
+  });
 });
diff --git a/test/parallel/test-runner-tags-experimental-warning.mjs b/test/parallel/test-runner-tags-experimental-warning.mjs
index 522cc781ed3e..4fbe46fd144a 100644
--- a/test/parallel/test-runner-tags-experimental-warning.mjs
+++ b/test/parallel/test-runner-tags-experimental-warning.mjs
@@ -50,7 +50,7 @@ test('--experimental-test-tag-filter fires the warning', () => {
   const { stderr } = runChild([
     '--test',
     '--test-reporter=tap',
-    '--experimental-test-tag-filter=db',
+    '--experimental-test-tag-filter=*',
     '--test-isolation=none',
     fixture,
   ]);
diff --git a/test/parallel/test-runner-tags-validation.mjs b/test/parallel/test-runner-tags-validation.mjs
index 4e0249479627..3b6138bbf782 100644
--- a/test/parallel/test-runner-tags-validation.mjs
+++ b/test/parallel/test-runner-tags-validation.mjs
@@ -37,6 +37,26 @@ test('empty-string tag throws ERR_INVALID_ARG_VALUE', () => {
   );
 });
 
+test('forbidden characters throw ERR_INVALID_ARG_VALUE', () => {
+  for (const bad of ['a b', 'a\tb', 'a\nb', 'a&b', 'a|b', 'a!b', 'a(b', 'a)b', 'a*b', '*', '&&', '||']) {
+    assert.throws(
+      () => test('x', { tags: [bad] }, () => {}),
+      { code: 'ERR_INVALID_ARG_VALUE' },
+      `expected throw for tag=${JSON.stringify(bad)}`,
+    );
+  }
+});
+
+test('reserved words throw ERR_INVALID_ARG_VALUE in any casing', () => {
+  for (const word of ['and', 'AND', 'And', 'or', 'OR', 'Or', 'not', 'NOT', 'Not']) {
+    assert.throws(
+      () => test('x', { tags: [word] }, () => {}),
+      { code: 'ERR_INVALID_ARG_VALUE' },
+      `expected throw for reserved word ${word}`,
+    );
+  }
+});
+
 test('Unicode and most punctuation are allowed', () => {
   // None of these should throw.
   test('unicode-1', { tags: ['café'] }, () => {});
@@ -80,7 +100,7 @@ test('suite() and describe() validate tags identically', () => {
     { code: 'ERR_INVALID_ARG_TYPE' },
   );
   assert.throws(
-    () => describe('s', { tags: [''] }, () => {}),
+    () => describe('s', { tags: ['and'] }, () => {}),
     { code: 'ERR_INVALID_ARG_VALUE' },
   );
 });
@@ -92,6 +112,13 @@ test('it() validates tags identically to test()', () => {
   );
 });
 
+test('it() validates tags identically to test()', () => {
+  assert.throws(
+    () => it('i', { tags: ['a b'] }, () => {}),
+    { code: 'ERR_INVALID_ARG_VALUE' },
+  );
+});
+
 test('run() rejects non-string testTagFilters values', () => {
   for (const bad of [[42], [{}], [null], [undefined], [true], [Symbol('s')]]) {
     assert.throws(

From f46e96fe54b1e240efa4b0a1b694b8aa2ef186a4 Mon Sep 17 00:00:00 2001
From: Edy Silva <edigleyssonsilva@gmail.com>
Date: Thu, 13 Aug 2026 10:59:56 -0300
Subject: [PATCH 2/4] sqlite: expose prepared statement statistics

Signed-off-by: geeksilva97 <edigleyssonsilva@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/64541
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
---
 doc/api/sqlite.md                           |  51 +++++
 src/node_sqlite.cc                          |  74 ++++++-
 src/node_sqlite.h                           |  28 +++
 test/parallel/test-sqlite-statement-sync.js | 206 ++++++++++++++++++++
 4 files changed, 353 insertions(+), 6 deletions(-)

diff --git a/doc/api/sqlite.md b/doc/api/sqlite.md
index 97eac5c5a139..e50a66e92621 100644
--- a/doc/api/sqlite.md
+++ b/doc/api/sqlite.md
@@ -1196,6 +1196,18 @@ returns an empty iterator. The prepared statement [parameters are bound][] using
 the values in `namedParameters` and `anonymousParameters`. See
 [Binding parameters][].
 
+### `statement.resetStats()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Resets every counter reported by [`statement.stat()`][] back to zero, except
+`memused`, which reports current memory usage and cannot be reset. This
+method is a wrapper around [`sqlite3_stmt_status()`][] and is useful for
+measuring a specific workload without the counts accumulated by earlier
+executions of the same prepared statement.
+
 ### `statement.run([namedParameters][, ...anonymousParameters])`
 
 <!-- YAML
@@ -1322,6 +1334,43 @@ added: REPLACEME
 Finalizes the prepared statement. If the prepared statement is already
 finalized, then this is a no-op.
 
+### `statement.stat(counter)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `counter` {string} The name of the counter to read. One of:
+
+  * `'fullscanStep'` The number of times SQLite has stepped forward in a table
+    as part of a full table scan.
+  * `'sort'` The number of sort operations that have occurred.
+  * `'autoindex'` The number of rows inserted into transient indices that were
+    created automatically to help joins run faster.
+  * `'vmStep'` The number of virtual machine operations executed by the
+    prepared statement.
+  * `'reprepare'` The number of times the statement has been automatically
+    reprepared due to schema changes or changes to bound parameters.
+  * `'run'` The number of execution cycles started by the prepared statement.
+  * `'filterMiss'` The number of times the Bloom filter returned a result that
+    required the join step to be processed as normal.
+  * `'filterHit'` The number of times a join step was bypassed because a Bloom
+    filter returned not-found.
+  * `'memused'` The approximate number of bytes of heap memory used to store
+    the prepared statement.
+
+* Returns: {number} The current value of the requested counter.
+
+Returns one of the runtime counters that SQLite tracks for this prepared
+statement. This method is a wrapper around [`sqlite3_stmt_status()`][] and does
+not reset the counter. Asserting that a statement does not perform a full table
+scan (`statement.stat('fullscanStep') === 0`) is a useful check to guard
+against degenerate performance.
+
+The `'filterMiss'` and `'filterHit'` counters require SQLite 3.38.0 or later.
+Builds linked against an older SQLite with `--shared-sqlite` do not expose them,
+and passing either name throws `ERR_INVALID_ARG_VALUE`.
+
 ## Class: `SQLTagStore`
 
 <!-- YAML
@@ -1840,6 +1889,7 @@ callback function to indicate what type of operation is being authorized.
 [`sqlite3_serialize()`]: https://sqlite.org/c3ref/serialize.html
 [`sqlite3_set_authorizer()`]: https://sqlite.org/c3ref/set_authorizer.html
 [`sqlite3_sql()`]: https://www.sqlite.org/c3ref/expanded_sql.html
+[`sqlite3_stmt_status()`]: https://www.sqlite.org/c3ref/stmt_status.html
 [`sqlite3changeset_apply()`]: https://www.sqlite.org/session/sqlite3changeset_apply.html
 [`sqlite3session_attach()`]: https://www.sqlite.org/session/sqlite3session_attach.html
 [`sqlite3session_changeset()`]: https://www.sqlite.org/session/sqlite3session_changeset.html
@@ -1848,6 +1898,7 @@ callback function to indicate what type of operation is being authorized.
 [`sqlite3session_patchset()`]: https://www.sqlite.org/session/sqlite3session_patchset.html
 [`statement.setAllowBareNamedParameters()`]: #statementsetallowbarenamedparametersenabled
 [`statement.setAllowUnknownNamedParameters()`]: #statementsetallowunknownnamedparametersenabled
+[`statement.stat()`]: #statementstatcounter
 [busy timeout]: https://sqlite.org/c3ref/busy_timeout.html
 [connection]: https://www.sqlite.org/c3ref/sqlite3.html
 [data types]: https://www.sqlite.org/datatype3.html
diff --git a/src/node_sqlite.cc b/src/node_sqlite.cc
index 9c80d18cdaab..156d4f2e5f5c 100644
--- a/src/node_sqlite.cc
+++ b/src/node_sqlite.cc
@@ -177,9 +177,11 @@ Local<DictionaryTemplate> getLazyIterTemplate(Environment* env) {
 }
 }  // namespace
 
-// Helper function to find limit info from JS property name
-static constexpr const LimitInfo* GetLimitInfoFromName(std::string_view name) {
-  for (const auto& info : kLimitMapping) {
+// Helper function to look up a mapping entry by its JS-facing name
+template <typename T, size_t N>
+static constexpr const T* FindByJsName(const std::array<T, N>& mapping,
+                                       std::string_view name) {
+  for (const auto& info : mapping) {
     if (name == info.js_name) {
       return &info;
     }
@@ -793,7 +795,8 @@ Intercepted DatabaseSyncLimits::LimitsGetter(
   Isolate* isolate = env->isolate();
 
   Utf8Value prop_name(isolate, property);
-  const LimitInfo* limit_info = GetLimitInfoFromName(prop_name.ToStringView());
+  const LimitInfo* limit_info =
+      FindByJsName(kLimitMapping, prop_name.ToStringView());
 
   if (limit_info == nullptr) {
     return Intercepted::kNo;  // Unknown property, let default handling occur
@@ -825,7 +828,8 @@ Intercepted DatabaseSyncLimits::LimitsSetter(
   Isolate* isolate = env->isolate();
 
   Utf8Value prop_name(isolate, property);
-  const LimitInfo* limit_info = GetLimitInfoFromName(prop_name.ToStringView());
+  const LimitInfo* limit_info =
+      FindByJsName(kLimitMapping, prop_name.ToStringView());
 
   if (limit_info == nullptr) {
     return Intercepted::kNo;
@@ -873,7 +877,8 @@ Intercepted DatabaseSyncLimits::LimitsQuery(
 
   Isolate* isolate = info.GetIsolate();
   Utf8Value prop_name(isolate, property);
-  const LimitInfo* limit_info = GetLimitInfoFromName(prop_name.ToStringView());
+  const LimitInfo* limit_info =
+      FindByJsName(kLimitMapping, prop_name.ToStringView());
 
   if (!limit_info) {
     return Intercepted::kNo;
@@ -2694,6 +2699,7 @@ void StatementSync::Finalize() {
 
 void StatementSync::InvalidateColumnNameCache() {
   cached_column_names_.clear();
+  cached_column_names_reprepare_count_ = -1;
 }
 
 inline bool StatementSync::IsFinalized() {
@@ -3350,6 +3356,60 @@ void StatementSync::ExpandedSQLGetter(const FunctionCallbackInfo<Value>& args) {
   args.GetReturnValue().Set(result);
 }
 
+void StatementSync::Stat(const FunctionCallbackInfo<Value>& args) {
+  StatementSync* stmt;
+  ASSIGN_OR_RETURN_UNWRAP(&stmt, args.This());
+  Environment* env = Environment::GetCurrent(args);
+  THROW_AND_RETURN_ON_BAD_STATE(
+      env, stmt->IsFinalized(), "statement has been finalized");
+  Isolate* isolate = env->isolate();
+
+  if (!args[0]->IsString()) {
+    THROW_ERR_INVALID_ARG_TYPE(isolate,
+                               "The \"counter\" argument must be a string.");
+    return;
+  }
+
+  Utf8Value counter(isolate, args[0].As<String>());
+  const StatusInfo* status_info =
+      FindByJsName(kStatusMapping, counter.ToStringView());
+  if (status_info == nullptr) {
+    THROW_ERR_INVALID_ARG_VALUE(
+        isolate, "The \"counter\" argument is not a valid statistic name.");
+    return;
+  }
+
+  // The reset flag is always false; the counter is read without being cleared.
+  int value = sqlite3_stmt_status(
+      stmt->statement_.get(), status_info->sqlite_status_id, false);
+  args.GetReturnValue().Set(Integer::New(isolate, value));
+}
+
+void StatementSync::ResetStats(const FunctionCallbackInfo<Value>& args) {
+  StatementSync* stmt;
+  ASSIGN_OR_RETURN_UNWRAP(&stmt, args.This());
+  Environment* env = Environment::GetCurrent(args);
+  THROW_AND_RETURN_ON_BAD_STATE(
+      env, stmt->IsFinalized(), "statement has been finalized");
+
+  // sqlite3_stmt_status() resets a single counter per call, so every exposed
+  // counter is visited. The returned value is the pre-reset one and is unused.
+  // SQLITE_STMTSTATUS_MEMUSED is skipped: it reports current memory usage
+  // rather than an accumulated counter, and SQLite ignores the reset flag for
+  // it.
+  for (const auto& info : kStatusMapping) {
+    if (info.sqlite_status_id == SQLITE_STMTSTATUS_MEMUSED) {
+      continue;
+    }
+    sqlite3_stmt_status(stmt->statement_.get(), info.sqlite_status_id, true);
+  }
+
+  // The column name cache is keyed on SQLITE_STMTSTATUS_REPREPARE, which was
+  // just zeroed. Without invalidating, a later re-prepare can make the counter
+  // match the cached generation again and the stale names would be reused.
+  stmt->InvalidateColumnNameCache();
+}
+
 void StatementSync::SetAllowBareNamedParameters(
     const FunctionCallbackInfo<Value>& args) {
   StatementSync* stmt;
@@ -3775,6 +3835,8 @@ Local<FunctionTemplate> StatementSync::GetConstructorTemplate(
                             tmpl,
                             FIXED_ONE_BYTE_STRING(isolate, "expandedSQL"),
                             StatementSync::ExpandedSQLGetter);
+    SetProtoMethodNoSideEffect(isolate, tmpl, "stat", StatementSync::Stat);
+    SetProtoMethod(isolate, tmpl, "resetStats", StatementSync::ResetStats);
     SetProtoMethod(isolate,
                    tmpl,
                    "setAllowBareNamedParameters",
diff --git a/src/node_sqlite.h b/src/node_sqlite.h
index 17025a528622..5f51a48fe1cc 100644
--- a/src/node_sqlite.h
+++ b/src/node_sqlite.h
@@ -52,6 +52,32 @@ static_assert(
     CheckLimitIndices(),
     "Each kLimitMapping entry's sqlite_limit_id must match its index");
 
+// Mapping from JavaScript counter names to SQLite statement status constants
+struct StatusInfo {
+  std::string_view js_name;
+  int sqlite_status_id;
+};
+
+// SQLITE_STMTSTATUS_FILTER_HIT and SQLITE_STMTSTATUS_FILTER_MISS require
+// SQLite >= 3.38.0. Older shared-library builds omit the two counters.
+#if SQLITE_VERSION_NUMBER >= 3038000
+#define NODE_SQLITE_HAS_FILTER_STATUS 1
+#endif
+
+inline constexpr auto kStatusMapping = std::to_array<StatusInfo>({
+    {"fullscanStep", SQLITE_STMTSTATUS_FULLSCAN_STEP},
+    {"sort", SQLITE_STMTSTATUS_SORT},
+    {"autoindex", SQLITE_STMTSTATUS_AUTOINDEX},
+    {"vmStep", SQLITE_STMTSTATUS_VM_STEP},
+    {"reprepare", SQLITE_STMTSTATUS_REPREPARE},
+    {"run", SQLITE_STMTSTATUS_RUN},
+#ifdef NODE_SQLITE_HAS_FILTER_STATUS
+    {"filterMiss", SQLITE_STMTSTATUS_FILTER_MISS},
+    {"filterHit", SQLITE_STMTSTATUS_FILTER_HIT},
+#endif
+    {"memused", SQLITE_STMTSTATUS_MEMUSED},
+});
+
 class DatabaseOpenConfiguration {
  public:
   explicit DatabaseOpenConfiguration(std::string&& location)
@@ -284,6 +310,8 @@ class StatementSync : public BaseObject {
   static void SourceSQLGetter(const v8::FunctionCallbackInfo<v8::Value>& args);
   static void ExpandedSQLGetter(
       const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void Stat(const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void ResetStats(const v8::FunctionCallbackInfo<v8::Value>& args);
   static void SetAllowBareNamedParameters(
       const v8::FunctionCallbackInfo<v8::Value>& args);
   static void SetAllowUnknownNamedParameters(
diff --git a/test/parallel/test-sqlite-statement-sync.js b/test/parallel/test-sqlite-statement-sync.js
index a55e19fd14f3..a52634f59ac6 100644
--- a/test/parallel/test-sqlite-statement-sync.js
+++ b/test/parallel/test-sqlite-statement-sync.js
@@ -564,6 +564,212 @@ suite('StatementSync.prototype.expandedSQL', () => {
   });
 });
 
+suite('StatementSync.prototype.stat()', () => {
+  const counters = [
+    'fullscanStep', 'sort', 'autoindex', 'vmStep', 'reprepare',
+    'run', 'memused',
+  ];
+
+  // 'filterMiss' and 'filterHit' map to SQLITE_STMTSTATUS_FILTER_MISS and
+  // SQLITE_STMTSTATUS_FILTER_HIT, which were added in SQLite 3.38.0. Builds
+  // using an older shared SQLite do not expose them.
+  const [major, minor] = process.versions.sqlite.split('.').map(Number);
+  const hasFilterCounters = major > 3 || (major === 3 && minor >= 38);
+
+  if (hasFilterCounters) {
+    counters.push('filterMiss', 'filterHit');
+  }
+
+  test('returns a number for every valid counter', (t) => {
+    using db = new DatabaseSync(':memory:');
+    db.exec('CREATE TABLE data(key INTEGER PRIMARY KEY, val TEXT) STRICT;');
+    const stmt = db.prepare('SELECT * FROM data');
+    for (const counter of counters) {
+      t.assert.strictEqual(typeof stmt.stat(counter), 'number');
+    }
+  });
+
+  test('counts virtual machine steps and runs after execution', (t) => {
+    using db = new DatabaseSync(':memory:');
+    db.exec('CREATE TABLE data(key INTEGER PRIMARY KEY, val TEXT) STRICT;');
+    const insert = db.prepare('INSERT INTO data (key, val) VALUES (?, ?)');
+    for (let i = 1; i <= 5; i++) {
+      insert.run(i, `val-${i}`);
+    }
+    const stmt = db.prepare('SELECT * FROM data');
+    t.assert.strictEqual(stmt.stat('run'), 0);
+    t.assert.strictEqual(stmt.stat('vmStep'), 0);
+    stmt.all();
+    t.assert.strictEqual(stmt.stat('run'), 1);
+    t.assert.ok(stmt.stat('vmStep') > 0);
+    t.assert.ok(stmt.stat('memused') > 0);
+  });
+
+  test('detects full table scans', (t) => {
+    using db = new DatabaseSync(':memory:');
+    db.exec('CREATE TABLE data(key INTEGER PRIMARY KEY, val TEXT) STRICT;');
+    const insert = db.prepare('INSERT INTO data (key, val) VALUES (?, ?)');
+    for (let i = 1; i <= 10; i++) {
+      insert.run(i, `val-${i}`);
+    }
+
+    // Filtering on a non-indexed column forces a full table scan.
+    const scan = db.prepare('SELECT * FROM data WHERE val = ?');
+    scan.all('val-5');
+    t.assert.ok(scan.stat('fullscanStep') > 0);
+
+    // Filtering on the primary key uses the index; no full scan occurs.
+    const indexed = db.prepare('SELECT * FROM data WHERE key = ?');
+    indexed.all(5);
+    t.assert.strictEqual(indexed.stat('fullscanStep'), 0);
+  });
+
+  test('reading a counter does not reset it', (t) => {
+    using db = new DatabaseSync(':memory:');
+    db.exec('CREATE TABLE data(key INTEGER PRIMARY KEY, val TEXT) STRICT;');
+    const stmt = db.prepare('SELECT * FROM data');
+    stmt.all();
+    const first = stmt.stat('run');
+    t.assert.strictEqual(stmt.stat('run'), first);
+  });
+
+  test('throws if the counter argument is not a string', (t) => {
+    using db = new DatabaseSync(':memory:');
+    const stmt = db.prepare('SELECT 1');
+    t.assert.throws(() => stmt.stat(), {
+      code: 'ERR_INVALID_ARG_TYPE',
+      message: /The "counter" argument must be a string/,
+    });
+    t.assert.throws(() => stmt.stat(42), {
+      code: 'ERR_INVALID_ARG_TYPE',
+      message: /The "counter" argument must be a string/,
+    });
+  });
+
+  test('throws if the counter name is unknown', (t) => {
+    using db = new DatabaseSync(':memory:');
+    const stmt = db.prepare('SELECT 1');
+    t.assert.throws(() => stmt.stat('nope'), {
+      code: 'ERR_INVALID_ARG_VALUE',
+      message: /The "counter" argument is not a valid statistic name/,
+    });
+  });
+
+  test('throws if the statement is finalized', (t) => {
+    const db = new DatabaseSync(':memory:');
+    const stmt = db.prepare('SELECT 1');
+    db.close();
+    t.assert.throws(() => stmt.stat('run'), {
+      code: 'ERR_INVALID_STATE',
+      message: /statement has been finalized/,
+    });
+  });
+});
+
+suite('StatementSync.prototype.resetStats()', () => {
+  test('returns undefined', (t) => {
+    using db = new DatabaseSync(':memory:');
+    const stmt = db.prepare('SELECT 1');
+    t.assert.strictEqual(stmt.resetStats(), undefined);
+  });
+
+  // The column name cache is keyed on the reprepare counter, which
+  // resetStats() zeroes. A later re-prepare must not be able to make the
+  // counter match the cached generation again and reuse stale names.
+  test('invalidates cached iterator column names', (t) => {
+    using db = new DatabaseSync(':memory:');
+    db.exec('CREATE TABLE data(a); INSERT INTO data VALUES (1)');
+    const stmt = db.prepare('SELECT * FROM data');
+
+    db.exec('ALTER TABLE data RENAME COLUMN a TO b');
+    stmt.iterate().toArray();
+    stmt.resetStats();
+    db.exec('ALTER TABLE data RENAME COLUMN b TO c');
+
+    t.assert.deepStrictEqual(stmt.iterate().toArray(), [
+      { __proto__: null, c: 1 },
+    ]);
+  });
+
+  test('invalidates the cache when the column count grows', (t) => {
+    using db = new DatabaseSync(':memory:');
+    db.exec('CREATE TABLE t(a); INSERT INTO t VALUES (1)');
+    const stmt = db.prepare('SELECT * FROM t');
+
+    db.exec('ALTER TABLE t ADD COLUMN b DEFAULT 2');
+    stmt.iterate().toArray();
+    stmt.resetStats();
+    db.exec('ALTER TABLE t ADD COLUMN c DEFAULT 3');
+
+    t.assert.deepStrictEqual(stmt.iterate().toArray(), [
+      { __proto__: null, a: 1, b: 2, c: 3 },
+    ]);
+  });
+
+  test('does not reset memused', (t) => {
+    using db = new DatabaseSync(':memory:');
+    db.exec('CREATE TABLE t(a); INSERT INTO t VALUES (1),(2),(3)');
+    const stmt = db.prepare('SELECT * FROM t ORDER BY a');
+    stmt.all();
+
+    // The memused counter reports current memory usage rather than an
+    // accumulated total, so SQLite ignores the reset flag for it.
+    const before = stmt.stat('memused');
+    t.assert.ok(before > 0);
+    stmt.resetStats();
+    t.assert.strictEqual(stmt.stat('memused'), before);
+  });
+
+  test('clears every counter', (t) => {
+    using db = new DatabaseSync(':memory:');
+    db.exec('CREATE TABLE data(key INTEGER PRIMARY KEY, val TEXT) STRICT;');
+    const insert = db.prepare('INSERT INTO data (key, val) VALUES (?, ?)');
+    for (let i = 1; i <= 5; i++) {
+      insert.run(i, `val-${i}`);
+    }
+
+    // Force a full table scan so more than one counter is non-zero.
+    const stmt = db.prepare('SELECT * FROM data WHERE val = ?');
+    stmt.all('val-3');
+    t.assert.ok(stmt.stat('run') > 0);
+    t.assert.ok(stmt.stat('vmStep') > 0);
+    t.assert.ok(stmt.stat('fullscanStep') > 0);
+
+    stmt.resetStats();
+    t.assert.strictEqual(stmt.stat('run'), 0);
+    t.assert.strictEqual(stmt.stat('vmStep'), 0);
+    t.assert.strictEqual(stmt.stat('fullscanStep'), 0);
+  });
+
+  test('counters accumulate again after a reset', (t) => {
+    using db = new DatabaseSync(':memory:');
+    db.exec('CREATE TABLE data(key INTEGER PRIMARY KEY, val TEXT) STRICT;');
+    const stmt = db.prepare('SELECT * FROM data');
+    stmt.all();
+    stmt.resetStats();
+    t.assert.strictEqual(stmt.stat('run'), 0);
+    stmt.all();
+    t.assert.strictEqual(stmt.stat('run'), 1);
+  });
+
+  test('is a no-op when no counters have been incremented', (t) => {
+    using db = new DatabaseSync(':memory:');
+    const stmt = db.prepare('SELECT 1');
+    stmt.resetStats();
+    t.assert.strictEqual(stmt.stat('run'), 0);
+  });
+
+  test('throws if the statement is finalized', (t) => {
+    const db = new DatabaseSync(':memory:');
+    const stmt = db.prepare('SELECT 1');
+    db.close();
+    t.assert.throws(() => stmt.resetStats(), {
+      code: 'ERR_INVALID_STATE',
+      message: /statement has been finalized/,
+    });
+  });
+});
+
 suite('StatementSync.prototype.setReadBigInts()', () => {
   test('BigInts support can be toggled', (t) => {
     const db = new DatabaseSync(':memory:');

From bcb680c08cd4b874745f40d2064163cea9ebebc8 Mon Sep 17 00:00:00 2001
From: Hendrik Liebau <mail@hendrik-liebau.de>
Date: Thu, 13 Aug 2026 16:36:25 +0200
Subject: [PATCH 3/4] test: cover `realpathSync` resolving symlinks after a
 FIFO stat

While walking a path, `realpathSync` skips the components it already
knows are real, and in that branch it reads the shared stat buffer to
decide whether the walk has reached a pipe or a socket. That buffer
holds the result of the last stat made anywhere in the process rather
than the last one made by the walk, so an unrelated stat of a FIFO ends
the walk early and the path comes back with its symlinks unresolved. The
unresolved path is then written to the cache, so every later resolution
repeats it.

The walk only takes that branch once the ancestors are established as
real, which is the state the module loader's cache is in. The test goes
through `require()` to reach it, where the stale read costs a second
copy of a module reached through a symlink.

Signed-off-by: Hendrik Liebau <mail@hendrik-liebau.de>
PR-URL: https://github.com/nodejs/node/pull/65113
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
---
 lib/fs.js                                     | 25 +++++--
 ...est-fs-realpath-async-stale-stat-values.js | 62 ++++++++++++++++
 .../test-fs-realpath-stale-stat-values.js     | 73 +++++++++++++++++++
 3 files changed, 153 insertions(+), 7 deletions(-)
 create mode 100644 test/parallel/test-fs-realpath-async-stale-stat-values.js
 create mode 100644 test/parallel/test-fs-realpath-stale-stat-values.js

diff --git a/lib/fs.js b/lib/fs.js
index 4fbdaf813018..81c4d2b9c884 100644
--- a/lib/fs.js
+++ b/lib/fs.js
@@ -81,7 +81,6 @@ const {
 
 const {
   FSReqCallback,
-  statValues,
 } = binding;
 const { toPathIfFileURL } = require('internal/url');
 const {
@@ -3254,6 +3253,11 @@ function realpathSync(p, options) {
   const seenLinks = new SafeMap();
   const knownHard = new SafeSet();
   const original = p;
+  // Whether the symlink this walk resolved last pointed at a pipe or a
+  // socket, which is where the walk stops. It cannot be read back from the
+  // shared stat buffer, which holds the last stat made anywhere in the
+  // process rather than the last one made here.
+  let reachedPipeOrSocket = false;
 
   // Current character position in p
   let pos;
@@ -3297,8 +3301,7 @@ function realpathSync(p, options) {
 
     // Continue if not a symlink, break if a pipe/socket
     if (knownHard.has(base) || cache?.get(base) === base) {
-      if (isFileType(statValues, S_IFIFO) ||
-          isFileType(statValues, S_IFSOCK)) {
+      if (reachedPipeOrSocket) {
         break;
       }
       continue;
@@ -3336,7 +3339,9 @@ function realpathSync(p, options) {
         }
       }
       if (linkTarget === null) {
-        binding.stat(base, false, undefined, true);
+        const targetStats = binding.stat(base, false, undefined, true);
+        reachedPipeOrSocket = isFileType(targetStats, S_IFIFO) ||
+          isFileType(targetStats, S_IFSOCK);
         linkTarget = binding.readlink(base, undefined);
       }
       resolvedLink = pathModule.resolve(previous, linkTarget);
@@ -3418,6 +3423,11 @@ function realpath(p, options, callback) {
 
   const seenLinks = new SafeMap();
   const knownHard = new SafeSet();
+  // Whether the symlink this walk resolved last pointed at a pipe or a
+  // socket, which is where the walk stops. It cannot be read back from the
+  // shared stat buffer, which holds the last stat made anywhere in the
+  // process rather than the last one made here.
+  let reachedPipeOrSocket = false;
 
   // Current character position in p
   let pos;
@@ -3466,8 +3476,7 @@ function realpath(p, options, callback) {
 
     // Continue if not a symlink, break if a pipe/socket
     if (knownHard.has(base)) {
-      if (isFileType(statValues, S_IFIFO) ||
-          isFileType(statValues, S_IFSOCK)) {
+      if (reachedPipeOrSocket) {
         return callback(null, encodeRealpathResult(p, options));
       }
       return process.nextTick(LOOP);
@@ -3497,9 +3506,11 @@ function realpath(p, options, callback) {
         return gotTarget(null, seenLinks.get(id));
       }
     }
-    fs.stat(base, (err) => {
+    fs.stat(base, (err, targetStats) => {
       if (err) return callback(err);
 
+      reachedPipeOrSocket = targetStats.isFIFO() || targetStats.isSocket();
+
       fs.readlink(base, (err, target) => {
         if (!isWindows) seenLinks.set(id, target);
         gotTarget(err, target);
diff --git a/test/parallel/test-fs-realpath-async-stale-stat-values.js b/test/parallel/test-fs-realpath-async-stale-stat-values.js
new file mode 100644
index 000000000000..83e8af7b3eaf
--- /dev/null
+++ b/test/parallel/test-fs-realpath-async-stale-stat-values.js
@@ -0,0 +1,62 @@
+'use strict';
+
+// The async realpath() reads the shared stat buffer the same way realpathSync()
+// did, to decide whether the walk has reached a pipe or a socket. The walk's
+// own fs.stat() does leave the right value there, but it is not read until
+// after fs.readlink() and a process.nextTick(), and any stat completing in that
+// window replaces it.
+//
+// Truncating the walk only costs something when a second symlink follows the
+// one being resolved, so the path used here has two.
+
+const common = require('../common');
+
+if (common.isWindows)
+  common.skip('no mkfifo on Windows');
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const tmpdir = require('../common/tmpdir');
+
+tmpdir.refresh();
+
+const real = tmpdir.resolve('real');
+const pkg = tmpdir.resolve('pkg');
+const fifo = tmpdir.resolve('fifo');
+
+fs.mkdirSync(real);
+fs.mkdirSync(pkg);
+fs.writeFileSync(path.join(real, 'index.js'), '');
+fs.symlinkSync(path.join('..', 'real'), path.join(pkg, 'sub'));
+fs.symlinkSync('pkg', tmpdir.resolve('link'));
+execFileSync('mkfifo', [fifo]);
+
+const throughLinks = tmpdir.resolve('link', 'sub', 'index.js');
+const expected = path.join(real, 'index.js');
+
+// Keep stats of the FIFO completing for as long as the walk runs, so that one
+// of them lands in the buffer during the window.
+let settled = false;
+(function statFifo() {
+  if (settled) return;
+  fs.stat(fifo, statFifo);
+})();
+
+let error;
+let resolvedPath;
+
+fs.realpath(throughLinks, common.mustCall((err, resolved) => {
+  settled = true;
+  error = err;
+  resolvedPath = resolved;
+}));
+
+// Asserted on exit rather than in the callback. An assertion that fails inside
+// this callback is lost: it does not reach an `uncaughtException` handler and
+// the process still exits 0, so the test would pass over the bug it covers.
+process.on('exit', () => {
+  assert.ifError(error);
+  assert.strictEqual(resolvedPath, expected);
+});
diff --git a/test/parallel/test-fs-realpath-stale-stat-values.js b/test/parallel/test-fs-realpath-stale-stat-values.js
new file mode 100644
index 000000000000..2a5dfdad7a45
--- /dev/null
+++ b/test/parallel/test-fs-realpath-stale-stat-values.js
@@ -0,0 +1,73 @@
+// Flags: --expose-internals
+'use strict';
+
+// Resolving a path must not depend on what was stat'ed before it.
+//
+// While walking a path, realpath skips the components it already knows are
+// real, and in that branch it consulted the shared stat buffer to decide
+// whether the walk had reached a pipe or a socket. That buffer holds the result
+// of the last stat made anywhere in the process, so an unrelated stat of a FIFO
+// made the walk stop early and hand back the path with its symlinks unresolved.
+// The unresolved path is then cached, so every later resolution repeats it.
+
+const common = require('../common');
+
+if (common.isWindows)
+  common.skip('no mkfifo on Windows');
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { realpathCacheKey } = require('internal/fs/utils');
+const tmpdir = require('../common/tmpdir');
+
+tmpdir.refresh();
+
+const pkg = tmpdir.resolve('pkg');
+const link = tmpdir.resolve('pkg-link');
+const fifo = tmpdir.resolve('fifo');
+
+fs.mkdirSync(pkg);
+fs.writeFileSync(path.join(pkg, 'index.js'), 'module.exports = {};\n');
+fs.writeFileSync(tmpdir.resolve('warm.js'), 'module.exports = {};\n');
+fs.symlinkSync('pkg', link);
+execFileSync('mkfifo', [fifo]);
+
+const throughLink = path.join(link, 'index.js');
+const throughReal = path.join(pkg, 'index.js');
+
+// The walk only skips a component once something has established it as real. A
+// cache carrying the ancestors is that state, and it is the state the module
+// loader's own cache is in after it has resolved anything else under the
+// directory.
+function ancestorCache() {
+  const cache = new Map();
+  let dir = '';
+  for (const part of tmpdir.path.split(path.sep).slice(1)) {
+    dir += path.sep + part;
+    cache.set(dir, dir);
+  }
+  return cache;
+}
+
+fs.statSync(path.join(pkg, 'index.js'));
+assert.strictEqual(
+  fs.realpathSync(throughLink, { [realpathCacheKey]: ancestorCache() }),
+  throughReal,
+);
+
+fs.statSync(fifo);
+assert.strictEqual(
+  fs.realpathSync(throughLink, { [realpathCacheKey]: ancestorCache() }),
+  throughReal,
+);
+
+// What the stale read costs through the module loader, whose cache puts the
+// walk in that same state: the symlink stays unresolved, so the file is loaded
+// a second time under a second name.
+require(tmpdir.resolve('warm.js'));
+fs.statSync(fifo);
+
+assert.strictEqual(require.resolve(throughLink), throughReal);
+assert.strictEqual(require(throughLink), require(throughReal));

From 525e8f43e08aeaca491f409de19a5dc685438711 Mon Sep 17 00:00:00 2001
From: Trivikram Kamat <16024985+trivikr@users.noreply.github.com>
Date: Thu, 13 Aug 2026 07:58:23 -0700
Subject: [PATCH 4/4] ffi: reject detached ArrayBuffers as pointers

Reject detached ArrayBuffers and ArrayBuffer views in getRawPointer()
and FFI pointer argument conversion. This prevents detached backing
stores from being silently passed to native functions as null pointers.

Signed-off-by: Kamat, Trivikram <16024985+trivikr@users.noreply.github.com>
Assisted-by: codex:gpt-5.6-sol
PR-URL: https://github.com/nodejs/node/pull/65083
Fixes: https://github.com/nodejs/node/issues/65082
Reviewed-By: Paolo Insogna <paolo@cowtech.it>
---
 lib/internal/ffi/fast-api.js     | 31 ++++++++++++++++++++++++++--
 src/ffi/data.cc                  | 19 +++++++++++++----
 src/ffi/fast.cc                  | 31 ++++++++++++++++++++++++++--
 src/ffi/types.cc                 | 13 ++++++++++++
 test/ffi/test-ffi-fast-buffer.js | 27 +++++++++++++++++++++++-
 test/ffi/test-ffi-memory.js      | 35 ++++++++++++++++++++++++++++++++
 6 files changed, 147 insertions(+), 9 deletions(-)

diff --git a/lib/internal/ffi/fast-api.js b/lib/internal/ffi/fast-api.js
index a232caa1af24..4d46b9c7a8bb 100644
--- a/lib/internal/ffi/fast-api.js
+++ b/lib/internal/ffi/fast-api.js
@@ -1,13 +1,16 @@
 'use strict';
 
 const {
+  ArrayBufferPrototypeGetDetached,
   ArrayPrototypeIncludes,
+  DataViewPrototypeGetBuffer,
   NumberIsInteger,
   ObjectDefineProperty,
   ReflectApply,
   SafeWeakMap,
   StringPrototypeIncludes,
   TypeError,
+  TypedArrayPrototypeGetBuffer,
 } = primordials;
 
 const {
@@ -16,7 +19,9 @@ const {
 
 const {
   isAnyArrayBuffer,
+  isArrayBuffer,
   isArrayBufferView,
+  isDataView,
 } = require('internal/util/types');
 
 const {
@@ -167,6 +172,28 @@ function getStringConversionPointer(state, value, index) {
   return entry.pointer;
 }
 
+function getRawPointerArg(value, index) {
+  let buffer;
+  let isView = false;
+  if (isArrayBuffer(value)) {
+    buffer = value;
+  } else if (isArrayBufferView(value)) {
+    isView = true;
+    buffer = isDataView(value) ?
+      DataViewPrototypeGetBuffer(value) :
+      TypedArrayPrototypeGetBuffer(value);
+  }
+
+  if (buffer !== undefined && isArrayBuffer(buffer) &&
+      ArrayBufferPrototypeGetDetached(buffer)) {
+    throwFFIArgError(isView ?
+      `Argument ${index} is an ArrayBufferView backed by a detached ArrayBuffer` :
+      `Argument ${index} is a detached ArrayBuffer`);
+  }
+
+  return getRawPointer(value);
+}
+
 function convertPointerArg(type, value, stringState, index) {
   validateFastPointerArg(type, value, index);
   if (needsNullPointerConversion(type) &&
@@ -177,7 +204,7 @@ function convertPointerArg(type, value, stringState, index) {
     return getStringConversionPointer(stringState, value, index);
   }
   if (hasPointerMemoryArg(type, value)) {
-    return getRawPointer(value);
+    return getRawPointerArg(value, index);
   }
   // Pointer-like values (e.g. BigInt addresses) are passed through, matching
   // ToFFIArgument in src/ffi/types.cc and the single-argument fast path.
@@ -287,7 +314,7 @@ function wrapWithRawPointerConversions(rawFn, argumentTypes, owner) {
         if (fastBufferInvoke !== undefined) {
           return fastBufferInvoke(arg);
         }
-        arg = getRawPointer(arg);
+        arg = getRawPointerArg(arg, 0);
       }
       return rawFn(arg);
     };
diff --git a/src/ffi/data.cc b/src/ffi/data.cc
index 73b575395c8c..6a8d54ca0d39 100644
--- a/src/ffi/data.cc
+++ b/src/ffi/data.cc
@@ -685,7 +685,7 @@ void ExportBytes(const FunctionCallbackInfo<Value>& args) {
       args[0]->IsArrayBufferView()) {
     view.ReadValue(args[0]);
     if (view.WasDetached()) {
-      THROW_ERR_INVALID_ARG_VALUE(env, "Invalid ArrayBufferView backing store");
+      THROW_ERR_INVALID_ARG_VALUE(env, "ArrayBuffer is detached");
       return;
     }
   } else {
@@ -749,15 +749,26 @@ void GetRawPointer(const FunctionCallbackInfo<Value>& args) {
   std::shared_ptr<BackingStore> store;
 
   if (args[0]->IsArrayBuffer()) {
-    store = args[0].As<ArrayBuffer>()->GetBackingStore();
+    Local<ArrayBuffer> buffer = args[0].As<ArrayBuffer>();
+    if (buffer->WasDetached()) {
+      THROW_ERR_INVALID_ARG_VALUE(env, "ArrayBuffer is detached");
+      return;
+    }
+    store = buffer->GetBackingStore();
   } else if (args[0]->IsSharedArrayBuffer()) {
     store = args[0].As<SharedArrayBuffer>()->GetBackingStore();
   } else if (args[0]->IsArrayBufferView()) {
+    Local<ArrayBufferView> view = args[0].As<ArrayBufferView>();
+    if (view->Buffer()->WasDetached()) {
+      THROW_ERR_INVALID_ARG_VALUE(
+          env, "ArrayBufferView is backed by a detached ArrayBuffer");
+      return;
+    }
     // Access the store here to ensure that it exists. Small typed arrays
     // may not have a store until this point and can instead be stored
     // entirely in-heap.
-    store = args[0].As<ArrayBufferView>()->Buffer()->GetBackingStore();
-    offset = args[0].As<ArrayBufferView>()->ByteOffset();
+    store = view->Buffer()->GetBackingStore();
+    offset = view->ByteOffset();
   } else {
     THROW_ERR_INVALID_ARG_TYPE(
         env,
diff --git a/src/ffi/fast.cc b/src/ffi/fast.cc
index 80ee49e08b28..919bacf061a8 100644
--- a/src/ffi/fast.cc
+++ b/src/ffi/fast.cc
@@ -246,18 +246,45 @@ extern "C" uintptr_t node_ffi_fast_buffer_data(v8::Local<v8::Value> value,
   // returns zero after throwing, preventing the native target from seeing an
   // invalid pointer value.
   constexpr uintptr_t kInvalidBuffer = std::numeric_limits<uintptr_t>::max();
+  v8::Isolate* isolate = options != nullptr ? options->isolate : nullptr;
 
   // Accept only memory-backed JS values in the native helper. Other pointer
   // conversions, including strings, stay in the JS wrapper so their temporary
   // lifetime is explicit.
   if (value->IsArrayBufferView()) {
+    v8::Local<v8::ArrayBufferView> view = value.As<v8::ArrayBufferView>();
+    if (view->Buffer()->WasDetached()) {
+      if (isolate != nullptr) {
+        // No HandleScope is active during a Fast API call, so open one before
+        // creating the error object.
+        v8::HandleScope scope(isolate);
+        THROW_ERR_INVALID_ARG_VALUE(
+            isolate,
+            "Argument %u is an ArrayBufferView backed by a detached "
+            "ArrayBuffer",
+            index);
+      }
+      return kInvalidBuffer;
+    }
     return PointerFromValue(value);
   }
-  if (value->IsArrayBuffer() || value->IsSharedArrayBuffer()) {
+  if (value->IsArrayBuffer()) {
+    if (value.As<v8::ArrayBuffer>()->WasDetached()) {
+      if (isolate != nullptr) {
+        // No HandleScope is active during a Fast API call, so open one before
+        // creating the error object.
+        v8::HandleScope scope(isolate);
+        THROW_ERR_INVALID_ARG_VALUE(
+            isolate, "Argument %u is a detached ArrayBuffer", index);
+      }
+      return kInvalidBuffer;
+    }
+    return PointerFromValue(value);
+  }
+  if (value->IsSharedArrayBuffer()) {
     return PointerFromValue(value);
   }
 
-  v8::Isolate* isolate = options != nullptr ? options->isolate : nullptr;
   if (isolate != nullptr) {
     // No HandleScope is active during a Fast API call, so open one before
     // creating the error object.
diff --git a/src/ffi/types.cc b/src/ffi/types.cc
index 9ba3cc4da448..db0c913c547d 100644
--- a/src/ffi/types.cc
+++ b/src/ffi/types.cc
@@ -700,6 +700,14 @@ Maybe<FFIArgumentCategory> ToFFIArgument(Environment* env,
       // invalidating that backing store during the active FFI call is
       // unsupported and dangerous.
       Local<ArrayBufferView> view = arg.As<ArrayBufferView>();
+      if (view->Buffer()->WasDetached()) {
+        THROW_ERR_INVALID_ARG_VALUE(
+            env,
+            "Argument %u is an ArrayBufferView backed by a detached "
+            "ArrayBuffer",
+            index);
+        return {};
+      }
       std::shared_ptr<BackingStore> store = view->Buffer()->GetBackingStore();
 
       if (!store) {
@@ -721,6 +729,11 @@ Maybe<FFIArgumentCategory> ToFFIArgument(Environment* env,
       // that backing store during the active FFI call is unsupported and
       // dangerous.
       Local<ArrayBuffer> buffer = arg.As<ArrayBuffer>();
+      if (buffer->WasDetached()) {
+        THROW_ERR_INVALID_ARG_VALUE(
+            env, "Argument %u is a detached ArrayBuffer", index);
+        return {};
+      }
       std::shared_ptr<BackingStore> store = buffer->GetBackingStore();
 
       if (!store) {
diff --git a/test/ffi/test-ffi-fast-buffer.js b/test/ffi/test-ffi-fast-buffer.js
index e4399ee8ee47..a6b196efc014 100644
--- a/test/ffi/test-ffi-fast-buffer.js
+++ b/test/ffi/test-ffi-fast-buffer.js
@@ -98,6 +98,10 @@ test('fast FFI string buffers survive reentrant callbacks', {
 
 test('optimized buffer signatures preserve pointer-like conversions', () => {
   const lib = new ffi.DynamicLibrary(libraryPath);
+  const asPointer = lib.getFunction('pointer_to_usize', {
+    arguments: ['pointer'],
+    return: 'u64',
+  });
   const asBuffer = lib.getFunction('pointer_to_usize', {
     arguments: ['buffer'],
     return: 'u64',
@@ -107,6 +111,10 @@ test('optimized buffer signatures preserve pointer-like conversions', () => {
     return: 'u64',
   });
 
+  function callPointer(value) {
+    return asPointer(value);
+  }
+
   function callBuffer(value) {
     return asBuffer(value);
   }
@@ -117,17 +125,34 @@ test('optimized buffer signatures preserve pointer-like conversions', () => {
 
   try {
     for (let i = 0; i < 100_000; i++) {
+      assert.strictEqual(callPointer(0n), 0n);
       assert.strictEqual(callBuffer(0n), 0n);
       assert.strictEqual(callArrayBuffer(0n), 0n);
     }
 
-    for (const call of [callBuffer, callArrayBuffer]) {
+    for (const call of [callPointer, callBuffer, callArrayBuffer]) {
       assert.strictEqual(call(null), 0n);
       assert.strictEqual(call(undefined), 0n);
       assert.notStrictEqual(call('ffi'), 0n);
 
       const bytes = Buffer.alloc(1);
       assert.strictEqual(call(bytes), ffi.getRawPointer(bytes));
+
+      const arrayBuffer = new ArrayBuffer(8);
+      const typedArray = new Uint8Array(arrayBuffer);
+      const dataView = new DataView(arrayBuffer);
+      arrayBuffer.transfer();
+
+      assert.throws(() => call(arrayBuffer), {
+        code: 'ERR_INVALID_ARG_VALUE',
+        message: 'Argument 0 is a detached ArrayBuffer',
+      });
+      for (const view of [typedArray, dataView]) {
+        assert.throws(() => call(view), {
+          code: 'ERR_INVALID_ARG_VALUE',
+          message: 'Argument 0 is an ArrayBufferView backed by a detached ArrayBuffer',
+        });
+      }
     }
   } finally {
     lib.close();
diff --git a/test/ffi/test-ffi-memory.js b/test/ffi/test-ffi-memory.js
index f17f56c410f8..ee88e9ef4151 100644
--- a/test/ffi/test-ffi-memory.js
+++ b/test/ffi/test-ffi-memory.js
@@ -146,6 +146,41 @@ test('ffi getRawPointer returns raw addresses for byte sources', () => {
   assert.strictEqual(sharedViewPointer, sharedArrayBufferPointer + 2n);
 });
 
+test('ffi rejects detached array buffers and views as pointers', () => {
+  const arrayBuffer = new ArrayBuffer(8);
+  const typedArray = new Uint8Array(arrayBuffer);
+  const dataView = new DataView(arrayBuffer);
+
+  arrayBuffer.transfer();
+
+  assert.throws(() => ffi.exportArrayBuffer(arrayBuffer, 0n, 0), {
+    code: 'ERR_INVALID_ARG_VALUE',
+    message: 'ArrayBuffer is detached',
+  });
+
+  for (const [value, rawPointerMessage, argumentMessage] of [
+    [
+      arrayBuffer,
+      'ArrayBuffer is detached',
+      'Argument 0 is a detached ArrayBuffer',
+    ],
+    ...[typedArray, dataView].map((view) => [
+      view,
+      'ArrayBufferView is backed by a detached ArrayBuffer',
+      'Argument 0 is an ArrayBufferView backed by a detached ArrayBuffer',
+    ]),
+  ]) {
+    assert.throws(() => ffi.getRawPointer(value), {
+      code: 'ERR_INVALID_ARG_VALUE',
+      message: rawPointerMessage,
+    });
+    assert.throws(() => symbols.pointer_to_usize(value), {
+      code: 'ERR_INVALID_ARG_VALUE',
+      message: argumentMessage,
+    });
+  }
+});
+
 test('ffi exportString and exportBuffer copy data into native memory', () => {
   withAllocations(common.mustCall((alloc) => {
     const stringPtr = alloc(16);