@blamejs/core 0.12.60 → 0.12.62

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- v0.12.62 (2026-05-26) — **`b.jtd` — JSON Type Definition validation (RFC 8927).** Validate JSON against a JSON Type Definition schema (RFC 8927) — a small, portable, cross-implementation schema language, the interop-friendly companion to the framework's fluent b.safeSchema builder. b.jtd.validate(schema, instance) returns an array of { instancePath, schemaPath } errors (empty = valid); b.jtd.isValid is the boolean form. All eight schema forms are supported — empty, type, enum, elements, properties (with optional / additional properties and nullable), values, discriminator (with mapping), and ref (with definitions) — including the integer-range and RFC 3339 timestamp types. A malformed schema is rejected at compile time with jtd/bad-schema rather than silently mis-validating. Verified against the official json-typedef-spec suites: all 316 validation cases and all 49 invalid-schema cases. **Added:** *`b.jtd.validate(schema, instance)` / `b.jtd.isValid(schema, instance)`* — `validate` returns the RFC 8927 error list — each `{ instancePath, schemaPath }` naming the offending value and the broken schema rule — and `isValid` is the boolean convenience form. Supports every JTD form and type: the numeric types enforce their exact ranges (int8 … uint32, float32 / float64), `timestamp` requires an RFC 3339 date-time, `properties` honours `optionalProperties` / `additionalProperties` / `nullable`, and `discriminator` selects a `mapping` schema by a tag property. The schema is checked for well-formedness before validation, so unknown keywords, multiple forms, bad refs, or a discriminator over a non-properties mapping all throw `jtd/bad-schema`. Use JTD for schemas you share across implementations or generate code from; use `b.safeSchema` for in-process fluent validation.
+
+- v0.12.61 (2026-05-26) — **`b.jsonPath` — JSONPath query (RFC 9535).** A full RFC 9535 JSONPath query evaluator, complementing the framework's JSONPath guards (which screen path strings). b.jsonPath.query(doc, path) compiles a path and returns the matched node values; b.jsonPath.paths returns their normalized locations. The complete surface is implemented: name / wildcard / index / slice selectors, descendant segments (..), filter selectors (?) with comparison and logical operators, relative (@) and absolute ($) embedded queries, and the five standard functions length / count / match / search / value — with the spec's well-typedness rules enforced at compile time so a malformed or ill-typed query is rejected rather than silently mis-evaluated. Descendant walks are node-capped to bound work on hostile input. Verified against all 703 cases of the official jsonpath-compliance-test-suite. **Added:** *`b.jsonPath.query(doc, path)` / `b.jsonPath.paths(doc, path)`* — `query` returns the array of node values selected by an RFC 9535 JSONPath; `paths` returns the normalized-path string of each match (e.g. `$['a'][1]['p']`). Supports every selector (name, wildcard `*`, index incl. negative, slice `start:end:step` incl. negative step, comma-separated selections), child and descendant (`..`) segments, and filter expressions with `==` / `!=` / `<` / `<=` / `>` / `>=`, `&&` / `||` / `!`, existence tests, and the standard functions. The well-typedness rules are checked when the path is compiled — a non-singular query used as a comparison operand, an ill-typed function argument, or a value-typed function used as a test all throw `json-path/invalid`. Pairs with `b.guardJsonPath`, which screens operator-supplied path strings before they reach the evaluator.
+
 - v0.12.60 (2026-05-25) — **`b.jsonMergePatch` — JSON Merge Patch (RFC 7396).** The simpler companion to JSON Patch: b.jsonMergePatch.merge applies an RFC 7396 merge patch (application/merge-patch+json), the partial-document PATCH body. A member present in the patch replaces or — for nested objects — merges into the target, a member whose value is null removes that key, and a patch that is itself an array, scalar, or null replaces the target wholesale. The inputs are never mutated (the merge runs on a deep copy) and member keys are written as literal own properties, so a "__proto__" member cannot reach any prototype. Verified against every RFC 7396 Appendix A test case. **Added:** *`b.jsonMergePatch.merge(target, patch)`* — Applies a JSON Merge Patch to a target document and returns the result without mutating either input. When the patch is an object it overlays the target (a null member deletes the key, a nested object merges recursively, any other value replaces); when the patch is an array, scalar, or null it replaces the whole target. Member keys are set via `Object.defineProperty`, so a `"__proto__"` member becomes a literal own key rather than altering a prototype. Pairs with `b.jsonPatch` — merge patch reads like the resource you want, JSON Patch expresses precise operations (array reordering, literal-null values).
 
 - v0.12.58 (2026-05-25) — **`b.jsonPointer` (RFC 6901) + `b.jsonPatch` (RFC 6902) — JSON Pointer + Patch.** Two related JSON primitives. b.jsonPointer.get references a value within a JSON document by RFC 6901 path (/foo/0/bar), handling the ~1 / ~0 escapes and array indices, and refusing pointers that do not resolve. b.jsonPatch.apply applies an RFC 6902 patch — add / remove / replace / move / copy / test — the standard HTTP PATCH payload (application/json-patch+json). It is atomic: operations run against a deep copy, so a failure at any step (an out-of-range index, a missing source, or a failed test) throws and leaves the input document untouched, and test compares values structurally. Verified against the official json-patch/json-patch-tests conformance suite (every enabled result and error case) plus the RFC 6901 §5 pointer examples. **Added:** *`b.jsonPointer.get(doc, pointer)` / `b.jsonPointer.parse(pointer)`* — Resolve an RFC 6901 JSON Pointer against a document — walking object keys and array indices, decoding `~1` → `/` and `~0` → `~`, and returning the whole document for the empty pointer. Throws `json-pointer/not-found` for a missing key, an out-of-range or non-numeric (leading-zero) array index, or descent into a primitive, and `json-pointer/bad-pointer` for a non-`/`-prefixed pointer. `parse` exposes the decoded reference tokens. · *`b.jsonPatch.apply(doc, operations)`* — Apply an RFC 6902 patch and return the result. Supports `add` (insert / append with `-` for arrays, set for objects, whole-document for `""`), `remove`, `replace` (overwrite an existing location), `move`, `copy`, and `test` (structural equality). Atomic — the patch runs on a deep copy, so the input `doc` is never mutated and any failure (unknown op, missing `path` / `value` / `from`, bad index, failed `test`, or moving a location into its own child) throws a typed error. Paths are RFC 6901 pointers resolved through `b.jsonPointer`; suitable for HTTP PATCH endpoints.

package/README.md

@@ -99,6 +99,8 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **Signed webhooks + API encryption** — SLH-DSA-SHAKE-256f default; ML-DSA-65 opt-in; ECIES API encryption (`b.webhook`, `b.crypto`)
 - **HPKE / HTTP signatures** — RFC 9180 HPKE with ML-KEM-1024 + HKDF-SHA3-512 + ChaCha20-Poly1305 (`b.crypto.hpke`); RFC 9421 HTTP Message Signatures with derived components and ed25519 / ML-DSA-65 (`b.crypto.httpSig`); RFC 9530 Content-Digest / Repr-Digest body-integrity fields (SHA-256 / SHA-512, legacy algorithms refused — `b.contentDigest`) to sign the digest rather than the whole body
 - **Link header** — RFC 8288 Web Linking codec (`b.linkHeader.parse` / `serialize`): parse and build `Link: <uri>; rel="next"` relations, the standard REST pagination mechanism; quote-aware (a comma inside a quoted parameter never splits the list)
+- **JSON Type Definition** — RFC 8927 validation (`b.jtd.validate` / `isValid`): portable, cross-implementation schema validation (all eight forms — type / enum / elements / properties / values / discriminator / ref / empty), returning instancePath / schemaPath errors; validated against the official 316-case suite. Interop companion to the fluent `b.safeSchema` builder
+- **JSONPath** — full RFC 9535 query evaluator (`b.jsonPath.query` / `paths`): name / wildcard / index / slice / descendant selectors, `?filter` expressions, and the five standard functions, with compile-time well-typedness checks (validated against the official 703-case compliance suite); complements the JSONPath guards
 - **JSON Pointer / Patch** — RFC 6901 `b.jsonPointer.get` (reference a value by `/foo/0/bar`) + RFC 6902 `b.jsonPatch.apply` (atomic add / remove / replace / move / copy / test for HTTP PATCH; the input document is never mutated, structural `test` comparison) + RFC 7396 `b.jsonMergePatch.merge` (the `merge-patch+json` partial-document format; both PATCH formats are prototype-pollution-safe)
 - **Canonical JSON** — RFC 8785 JSON Canonicalization Scheme (`b.canonicalJson.stringifyJcs`): the deterministic, sorted-key byte form to hash or sign (custom credentials, receipts, deterministic request signing); UTF-16 key ordering + ECMAScript number formatting, with a lenient `stringify` variant for Buffers / Dates / BigInts
 - **Structured Fields** — full RFC 9651 codec (`b.structuredFields.parse` / `serialize`): Items / Lists / Dictionaries, Inner Lists, Parameters, and every bare-item type (Integer / Decimal / String / Token / Byte Sequence / Boolean / Date / Display String) with strict grammar + range enforcement — the parser behind Content-Digest, Client Hints, and HTTP Message Signatures

package/index.js

@@ -401,6 +401,8 @@ var linkHeader = require("./lib/link-header");
 var jsonPointer = require("./lib/json-pointer");
 var jsonPatch = require("./lib/json-patch");
 var jsonMergePatch = require("./lib/json-merge-patch");
+var jsonPath = require("./lib/json-path");
+var jtd = require("./lib/jtd");
 var standardWebhooks = require("./lib/standard-webhooks");
 var lro = require("./lib/lro");
 var jsonApi = require("./lib/jsonapi");
@@ -423,6 +425,8 @@ module.exports = {
   jsonPointer:      jsonPointer,
   jsonPatch:        jsonPatch,
   jsonMergePatch:   jsonMergePatch,
+  jsonPath:         jsonPath,
+  jtd:              jtd,
   standardWebhooks: standardWebhooks,
   lro:              lro,
   jsonApi:          jsonApi,

package/lib/json-path.js

@@ -0,0 +1,638 @@
+"use strict";
+/**
+ * @module b.jsonPath
+ * @nav    Data
+ * @title  JSONPath
+ *
+ * @intro
+ *   Query a JSON value with JSONPath (RFC 9535) — the standardized path
+ *   language for selecting nodes from a document
+ *   (<code>$.store.book[?@.price &lt; 10].title</code>). This is the
+ *   query evaluator that complements the framework's JSONPath
+ *   <em>guards</em> (<code>b.guardJsonPath</code>, which screen
+ *   operator-supplied path strings): <code>query</code> compiles a path
+ *   and returns the matched values, <code>paths</code> returns their
+ *   normalized locations.
+ *
+ *   The full RFC 9535 surface is implemented — name / wildcard / index /
+ *   slice selectors, descendant segments (<code>..</code>), filter
+ *   selectors (<code>?</code>) with comparison and logical operators and
+ *   relative (<code>@</code>) / absolute (<code>$</code>) queries, and
+ *   the five standard functions <code>length</code>, <code>count</code>,
+ *   <code>match</code>, <code>search</code>, and <code>value</code> — with
+ *   the spec's well-typedness rules enforced at compile time (a
+ *   malformed or ill-typed query is rejected, not silently mis-evaluated).
+ *
+ * @card
+ *   JSONPath query (RFC 9535) — select nodes from a JSON document with
+ *   the standard path language: name / wildcard / index / slice /
+ *   descendant selectors, <code>?filter</code> expressions, and the five
+ *   standard functions, with compile-time well-typedness checks.
+ */
+
+var { defineClass } = require("./framework-error");
+
+var JsonPathError = defineClass("JsonPathError", { alwaysPermanent: true });
+
+var MAX_DESCEND_NODES = 1000000;                             // allow:raw-byte-literal — DoS ceiling on nodes visited by a descendant walk
+
+// ---------------------------------------------------------------------------
+// Parser — recursive descent over the RFC 9535 ABNF.
+// ---------------------------------------------------------------------------
+
+function _isBlank(c) { return c === " " || c === "\t" || c === "\n" || c === "\r"; }
+function _isDigit(c) { return c >= "0" && c <= "9"; }
+// member-name-shorthand name-first: ALPHA / "_" / non-ASCII.
+function _isNameFirst(c) { var cc = c.charCodeAt(0); return (c >= "A" && c <= "Z") || (c >= "a" && c <= "z") || c === "_" || cc >= 0x80; }
+function _isNameChar(c) { return _isNameFirst(c) || _isDigit(c); }
+
+function _Parser(s) { this.s = s; this.i = 0; }
+_Parser.prototype.err = function (msg) { throw new JsonPathError("json-path/invalid", "jsonPath: " + msg + " at index " + this.i); };
+_Parser.prototype.peek = function () { return this.i < this.s.length ? this.s.charAt(this.i) : ""; };
+_Parser.prototype.eat = function (c) { if (this.peek() !== c) this.err("expected '" + c + "'"); this.i += 1; };
+_Parser.prototype.skipBlank = function () { while (_isBlank(this.peek())) this.i += 1; };
+
+_Parser.prototype.parseQuery = function () {
+  if (this.peek() !== "$") this.err("query must start with '$'");
+  this.i += 1;
+  var segments = this.parseSegments();
+  if (this.i !== this.s.length) this.err("trailing characters");
+  return { type: "root", segments: segments };
+};
+
+_Parser.prototype.parseSegments = function () {
+  var segs = [];
+  for (;;) {
+    var save = this.i;
+    this.skipBlank();
+    var c = this.peek();
+    if (c === "[") { segs.push({ kind: "child", selectors: this.parseBracket() }); }
+    else if (c === ".") {
+      if (this.s.charAt(this.i + 1) === ".") { this.i += 2; segs.push(this.parseDescendant()); }
+      else { this.i += 1; segs.push({ kind: "child", selectors: [this.parseShorthand()] }); }
+    } else { this.i = save; break; }
+  }
+  return segs;
+};
+
+_Parser.prototype.parseDescendant = function () {
+  var c = this.peek();
+  if (c === "[") return { kind: "descendant", selectors: this.parseBracket() };
+  if (c === "*") { this.i += 1; return { kind: "descendant", selectors: [{ type: "wildcard" }] }; }
+  return { kind: "descendant", selectors: [this.parseShorthand()] };
+};
+
+_Parser.prototype.parseShorthand = function () {
+  var c = this.peek();
+  if (c === "*") { this.i += 1; return { type: "wildcard" }; }
+  if (!_isNameFirst(c)) this.err("invalid member name");
+  var start = this.i; this.i += 1;
+  while (_isNameChar(this.peek())) this.i += 1;
+  return { type: "name", name: this.s.slice(start, this.i) };
+};
+
+_Parser.prototype.parseBracket = function () {
+  this.eat("[");
+  var selectors = [];
+  for (;;) {
+    this.skipBlank();
+    selectors.push(this.parseSelector());
+    this.skipBlank();
+    var c = this.peek();
+    if (c === ",") { this.i += 1; continue; }
+    if (c === "]") { this.i += 1; break; }
+    this.err("expected ',' or ']' in selection");
+  }
+  return selectors;
+};
+
+_Parser.prototype.parseSelector = function () {
+  var c = this.peek();
+  if (c === "*") { this.i += 1; return { type: "wildcard" }; }
+  if (c === "'" || c === "\"") return { type: "name", name: this.parseStringLiteral() };
+  if (c === "?") { this.i += 1; this.skipBlank(); return { type: "filter", expr: this.parseLogicalOr() }; }
+  // index or slice
+  if (c === ":" || c === "-" || _isDigit(c)) return this.parseIndexOrSlice();
+  this.err("invalid selector");
+};
+
+_Parser.prototype.parseIntToken = function () {
+  var start = this.i;
+  if (this.peek() === "-") this.i += 1;
+  if (!_isDigit(this.peek())) this.err("expected integer");
+  if (this.peek() === "0") {
+    this.i += 1;
+    if (_isDigit(this.peek())) this.err("leading zero in integer");
+  } else {
+    while (_isDigit(this.peek())) this.i += 1;
+  }
+  var txt = this.s.slice(start, this.i);
+  if (txt === "-0") this.err("negative zero");
+  var n = Number(txt);
+  if (!Number.isSafeInteger(n)) this.err("integer out of range");
+  return n;
+};
+
+_Parser.prototype.parseIndexOrSlice = function () {
+  // Detect slice by looking for ':' before ',' or ']' (whitespace-aware).
+  var isSlice = false, j = this.i;
+  while (j < this.s.length) {
+    var ch = this.s.charAt(j);
+    if (ch === ":") { isSlice = true; break; }
+    if (ch === "," || ch === "]") break;
+    if (_isBlank(ch)) { j += 1; continue; }
+    if (ch === "-" || _isDigit(ch)) { j += 1; continue; }
+    break;
+  }
+  if (!isSlice) { return { type: "index", index: this.parseIntToken() }; }
+  // slice: [start] ":" [end] [ ":" [step] ]
+  var start = null, end = null, step = null;
+  this.skipBlank();
+  if (this.peek() === "-" || _isDigit(this.peek())) start = this.parseIntToken();
+  this.skipBlank(); this.eat(":"); this.skipBlank();
+  if (this.peek() === "-" || _isDigit(this.peek())) end = this.parseIntToken();
+  this.skipBlank();
+  if (this.peek() === ":") {
+    this.i += 1; this.skipBlank();
+    if (this.peek() === "-" || _isDigit(this.peek())) step = this.parseIntToken();
+  }
+  return { type: "slice", start: start, end: end, step: step };
+};
+
+_Parser.prototype.parseStringLiteral = function () {
+  var quote = this.peek(); this.i += 1;
+  var out = "";
+  for (;;) {
+    if (this.i >= this.s.length) this.err("unterminated string");
+    var c = this.s.charAt(this.i); this.i += 1;
+    if (c === quote) return out;
+    if (c === "\\") {
+      var e = this.s.charAt(this.i); this.i += 1;
+      if (e === "n") out += "\n";
+      else if (e === "t") out += "\t";
+      else if (e === "r") out += "\r";
+      else if (e === "b") out += "\b";
+      else if (e === "f") out += "\f";
+      else if (e === "/") out += "/";
+      else if (e === "\\") out += "\\";
+      else if (e === quote) out += quote;
+      else if (e === "u") {
+        var hex = this.s.substr(this.i, 4);
+        if (!/^[0-9a-fA-F]{4}$/.test(hex)) this.err("invalid \\u escape");
+        var cp = parseInt(hex, 16); this.i += 4;             // allow:raw-byte-literal — base-16 radix for \uXXXX
+        // Surrogate pair handling.
+        if (cp >= 0xD800 && cp <= 0xDBFF && this.s.substr(this.i, 2) === "\\u") {
+          var hex2 = this.s.substr(this.i + 2, 4);
+          if (/^[0-9a-fA-F]{4}$/.test(hex2)) {
+            var lo = parseInt(hex2, 16);                     // allow:raw-byte-literal — base-16 radix for \uXXXX low surrogate
+            if (lo >= 0xDC00 && lo <= 0xDFFF) { out += String.fromCharCode(cp, lo); this.i += 6; continue; }
+          }
+          this.err("invalid surrogate pair");
+        }
+        if (cp >= 0xD800 && cp <= 0xDFFF) this.err("lone surrogate in string");
+        out += String.fromCharCode(cp);
+      } else this.err("invalid escape");
+    } else {
+      var cc = c.charCodeAt(0);
+      if (cc <= 0x1f) this.err("unescaped control character in string");
+      // RFC 9535: a literal of the SAME quote must be escaped; the other
+      // quote is allowed literally (handled by the quote check above).
+      out += c;
+    }
+  }
+};
+
+// --- filter expression grammar ---
+// Each node carries a `vtype`: "value" (ValueType), "logical" (LogicalType),
+// or "nodes" (NodesType) for well-typedness checks.
+
+_Parser.prototype.parseLogicalOr = function () {
+  var left = this.parseLogicalAnd();
+  for (;;) {
+    this.skipBlank();
+    if (this.s.substr(this.i, 2) === "||") { this.i += 2; this.skipBlank(); var r = this.parseLogicalAnd(); left = { type: "or", a: left, b: r, vtype: "logical" }; }
+    else break;
+  }
+  return left;
+};
+_Parser.prototype.parseLogicalAnd = function () {
+  var left = this.parseBasic();
+  for (;;) {
+    this.skipBlank();
+    if (this.s.substr(this.i, 2) === "&&") { this.i += 2; this.skipBlank(); var r = this.parseBasic(); left = { type: "and", a: left, b: r, vtype: "logical" }; }
+    else break;
+  }
+  return left;
+};
+_Parser.prototype.parseBasic = function () {
+  this.skipBlank();
+  if (this.peek() === "!") { this.i += 1; this.skipBlank(); var inner = this.parseBasic(); this._requireTestable(inner); return { type: "not", e: inner, vtype: "logical" }; }
+  if (this.peek() === "(") {
+    this.i += 1; this.skipBlank(); var e = this.parseLogicalOr(); this.skipBlank(); this.eat(")");
+    return e;
+  }
+  // comparison or test
+  var first = this.parseComparableOrQuery();
+  this.skipBlank();
+  var op = this._peekCompareOp();
+  if (op) {
+    this.i += op.length; this.skipBlank();
+    var second = this.parseComparableOrQuery();
+    this._requireComparable(first); this._requireComparable(second);
+    return { type: "compare", op: op, a: first, b: second, vtype: "logical" };
+  }
+  // test-expr: a query (existence) or a LogicalType function
+  this._requireTestable(first);
+  return first;
+};
+
+_Parser.prototype._peekCompareOp = function () {
+  var two = this.s.substr(this.i, 2);
+  if (two === "==" || two === "!=" || two === "<=" || two === ">=") return two;
+  var one = this.peek();
+  if (one === "<" || one === ">") return one;
+  return null;
+};
+
+// A comparable: literal / singular-query / function-expr. A query here may
+// be non-singular (NodesType) when used as a test; the caller checks type.
+_Parser.prototype.parseComparableOrQuery = function () {
+  var c = this.peek();
+  if (c === "'" || c === "\"") return { type: "lit", value: this.parseStringLiteral(), vtype: "value" };
+  if (c === "$" || c === "@") return this.parseFilterQuery();
+  if (_isDigit(c) || c === "-") return { type: "lit", value: this.parseNumber(), vtype: "value" };
+  if (this.s.substr(this.i, 4) === "true") { this.i += 4; return { type: "lit", value: true, vtype: "value" }; }
+  if (this.s.substr(this.i, 5) === "false") { this.i += 5; return { type: "lit", value: false, vtype: "value" }; }
+  if (this.s.substr(this.i, 4) === "null") { this.i += 4; return { type: "lit", value: null, vtype: "value" }; }
+  // function call
+  if (/^[a-z]/.test(c)) return this.parseFunction();
+  this.err("expected a comparable or query in filter");
+};
+
+_Parser.prototype.parseNumber = function () {
+  var start = this.i;
+  if (this.peek() === "-") this.i += 1;
+  if (this.peek() === "0") this.i += 1;
+  else { if (!_isDigit(this.peek())) this.err("invalid number"); while (_isDigit(this.peek())) this.i += 1; }
+  if (this.peek() === ".") { this.i += 1; if (!_isDigit(this.peek())) this.err("invalid fraction"); while (_isDigit(this.peek())) this.i += 1; }
+  if (this.peek() === "e" || this.peek() === "E") {
+    this.i += 1; if (this.peek() === "+" || this.peek() === "-") this.i += 1;
+    if (!_isDigit(this.peek())) this.err("invalid exponent"); while (_isDigit(this.peek())) this.i += 1;
+  }
+  return Number(this.s.slice(start, this.i));
+};
+
+_Parser.prototype.parseFilterQuery = function () {
+  var rootChar = this.peek(); this.i += 1; // $ or @
+  var segments = this.parseSegments();
+  var singular = segments.every(function (seg) {
+    return seg.kind === "child" && seg.selectors.length === 1 &&
+      (seg.selectors[0].type === "name" || seg.selectors[0].type === "index");
+  });
+  return { type: "query", root: rootChar, segments: segments, singular: singular, vtype: singular ? "value" : "nodes" };
+};
+
+var FUNCTIONS = {
+  length: { params: ["value"], ret: "value" },
+  count: { params: ["nodes"], ret: "value" },
+  value: { params: ["nodes"], ret: "value" },
+  match: { params: ["value", "value"], ret: "logical" },
+  search: { params: ["value", "value"], ret: "logical" },
+};
+
+_Parser.prototype.parseFunction = function () {
+  var start = this.i;
+  while (/[a-z]/.test(this.peek()) || this.peek() === "_" || _isDigit(this.peek())) this.i += 1;
+  var name = this.s.slice(start, this.i);
+  if (!Object.prototype.hasOwnProperty.call(FUNCTIONS, name)) this.err("unknown function '" + name + "'");
+  var spec = FUNCTIONS[name];
+  this.eat("(");
+  var args = [];
+  this.skipBlank();
+  if (this.peek() !== ")") {
+    for (;;) {
+      this.skipBlank();
+      args.push(this.parseFunctionArg());
+      this.skipBlank();
+      if (this.peek() === ",") { this.i += 1; continue; }
+      break;
+    }
+  }
+  this.skipBlank(); this.eat(")");
+  if (args.length !== spec.params.length) this.err("function '" + name + "' expects " + spec.params.length + " argument(s)");
+  for (var k = 0; k < args.length; k++) {
+    if (!_argMatches(spec.params[k], args[k])) this.err("function '" + name + "' argument " + (k + 1) + " type mismatch");
+  }
+  return { type: "func", name: name, args: args, vtype: spec.ret };
+};
+
+_Parser.prototype.parseFunctionArg = function () {
+  var c = this.peek();
+  if (c === "'" || c === "\"") return { type: "lit", value: this.parseStringLiteral(), vtype: "value" };
+  if (c === "$" || c === "@") return this.parseFilterQuery();
+  if (_isDigit(c) || c === "-") return { type: "lit", value: this.parseNumber(), vtype: "value" };
+  if (this.s.substr(this.i, 4) === "true") { this.i += 4; return { type: "lit", value: true, vtype: "value" }; }
+  if (this.s.substr(this.i, 5) === "false") { this.i += 5; return { type: "lit", value: false, vtype: "value" }; }
+  if (this.s.substr(this.i, 4) === "null") { this.i += 4; return { type: "lit", value: null, vtype: "value" }; }
+  if (/^[a-z]/.test(c)) return this.parseFunction();
+  if (c === "!" || c === "(") return this.parseLogicalOr();   // logical arg (none of the std funcs take it, caught by type check)
+  this.err("invalid function argument");
+};
+
+// A function parameter of declared type accepts: value←value-typed arg
+// (literal / singular query / value-returning function); nodes←any query
+// or nodes-returning function; logical←logical expr or logical function.
+function _argMatches(param, arg) {
+  if (param === "value") return arg.vtype === "value" || (arg.type === "query" && arg.singular);
+  if (param === "nodes") return arg.type === "query" || (arg.type === "func" && arg.vtype === "nodes");
+  if (param === "logical") return arg.vtype === "logical";
+  return false;
+}
+
+_Parser.prototype._requireComparable = function (node) {
+  // Comparables must be ValueType: a literal, a SINGULAR query, or a
+  // value-returning function. A non-singular query or logical/nodes
+  // function is ill-typed.
+  if (node.type === "lit") return;
+  if (node.type === "query") { if (!node.singular) this.err("non-singular query is not comparable"); return; }
+  if (node.type === "func") { if (node.vtype !== "value") this.err("function '" + node.name + "' is not comparable (not ValueType)"); return; }
+  this.err("operand is not comparable");
+};
+_Parser.prototype._requireTestable = function (node) {
+  // A test-expr is a query (existence) or a LogicalType function; a
+  // ValueType function (length/count/value) is NOT a valid test.
+  if (node.type === "query") return;
+  if (node.type === "func") { if (node.vtype !== "logical") this.err("function '" + node.name + "' is not a valid test (not LogicalType)"); return; }
+  if (node.vtype === "logical") return;
+  this.err("expression is not a valid test");
+};
+
+function _parse(path) {
+  if (typeof path !== "string") throw new JsonPathError("json-path/bad-arg", "jsonPath: path must be a string");
+  return new _Parser(path).parseQuery();
+}
+
+// ---------------------------------------------------------------------------
+// Evaluator — produces a nodelist of { value, path: [tokens] }.
+// ---------------------------------------------------------------------------
+
+function _isObject(v) { return v !== null && typeof v === "object" && !Array.isArray(v); }
+
+function _applySelector(sel, node, root, out) {
+  var v = node.value;
+  if (sel.type === "name") {
+    if (_isObject(v) && Object.prototype.hasOwnProperty.call(v, sel.name)) out.push({ value: v[sel.name], path: node.path.concat(sel.name) });
+  } else if (sel.type === "wildcard") {
+    if (Array.isArray(v)) { for (var i = 0; i < v.length; i++) out.push({ value: v[i], path: node.path.concat(i) }); }
+    else if (_isObject(v)) { Object.keys(v).forEach(function (k) { out.push({ value: v[k], path: node.path.concat(k) }); }); }
+  } else if (sel.type === "index") {
+    if (Array.isArray(v)) { var idx = sel.index < 0 ? v.length + sel.index : sel.index; if (idx >= 0 && idx < v.length) out.push({ value: v[idx], path: node.path.concat(idx) }); }
+  } else if (sel.type === "slice") {
+    if (Array.isArray(v)) _applySlice(sel, v, node, out);
+  } else if (sel.type === "filter") {
+    var items = Array.isArray(v) ? v.map(function (e, i) { return { value: e, path: node.path.concat(i) }; })
+      : _isObject(v) ? Object.keys(v).map(function (k) { return { value: v[k], path: node.path.concat(k) }; }) : [];
+    items.forEach(function (it) { if (_truthy(_evalLogical(sel.expr, it, root))) out.push(it); });
+  }
+}
+
+function _applySlice(sel, arr, node, out) {
+  var len = arr.length;
+  var step = sel.step === null ? 1 : sel.step;
+  if (step === 0) return;
+  var lower, upper, start, end;
+  if (step > 0) {
+    start = sel.start === null ? 0 : sel.start;
+    end = sel.end === null ? len : sel.end;
+    lower = start < 0 ? Math.max(len + start, 0) : Math.min(start, len);
+    upper = end < 0 ? Math.max(len + end, 0) : Math.min(end, len);
+    for (var i = lower; i < upper; i += step) out.push({ value: arr[i], path: node.path.concat(i) });
+  } else {
+    start = sel.start === null ? len - 1 : sel.start;
+    end = sel.end === null ? -len - 1 : sel.end;
+    lower = start < 0 ? Math.max(len + start, -1) : Math.min(start, len - 1);
+    upper = end < 0 ? Math.max(len + end, -1) : Math.min(end, len - 1);
+    for (var j = lower; j > upper; j += step) out.push({ value: arr[j], path: node.path.concat(j) });
+  }
+}
+
+function _descend(node, acc, budget) {
+  acc.push(node);
+  if (budget.n++ > MAX_DESCEND_NODES) throw new JsonPathError("json-path/too-large", "jsonPath: descendant walk exceeded the node cap");
+  var v = node.value;
+  if (Array.isArray(v)) { for (var i = 0; i < v.length; i++) _descend({ value: v[i], path: node.path.concat(i) }, acc, budget); }
+  else if (_isObject(v)) { Object.keys(v).forEach(function (k) { _descend({ value: v[k], path: node.path.concat(k) }, acc, budget); }); }
+}
+
+function _evalSegments(segments, root) {
+  var nodes = [{ value: root, path: [] }];
+  for (var s = 0; s < segments.length; s++) {
+    var seg = segments[s];
+    var next = [];
+    var base = nodes;
+    if (seg.kind === "descendant") {
+      var acc = []; var budget = { n: 0 };
+      nodes.forEach(function (nd) { _descend(nd, acc, budget); });
+      base = acc;
+    }
+    base.forEach(function (nd) { seg.selectors.forEach(function (sel) { _applySelector(sel, nd, root, next); }); });
+    nodes = next;
+  }
+  return nodes;
+}
+
+// --- filter evaluation ---
+var NOTHING = { __nothing: true };   // the "Nothing" value (missing node)
+
+function _singularValue(q, current, root) {
+  var node = q.root === "$" ? root : current.value;
+  for (var i = 0; i < q.segments.length; i++) {
+    var sel = q.segments[i].selectors[0];
+    if (sel.type === "name") {
+      if (!_isObject(node) || !Object.prototype.hasOwnProperty.call(node, sel.name)) return NOTHING;
+      node = node[sel.name];
+    } else { // index
+      if (!Array.isArray(node)) return NOTHING;
+      var idx = sel.index < 0 ? node.length + sel.index : sel.index;
+      if (idx < 0 || idx >= node.length) return NOTHING;
+      node = node[idx];
+    }
+  }
+  return node;
+}
+
+function _queryNodes(q, current, root) {
+  var startVal = q.root === "$" ? root : current.value;
+  return _evalSegments(q.segments, startVal);
+}
+
+function _evalComparable(node, current, root) {
+  if (node.type === "lit") return node.value;
+  if (node.type === "query") return _singularValue(node, current, root);
+  if (node.type === "func") return _evalFunctionValue(node, current, root);
+  return NOTHING;
+}
+
+function _deepEqual(a, b) {
+  if (a === b) return true;
+  if (a === null || b === null || typeof a !== "object" || typeof b !== "object") return a === b;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a)) { if (a.length !== b.length) return false; for (var i = 0; i < a.length; i++) if (!_deepEqual(a[i], b[i])) return false; return true; }
+  var ka = Object.keys(a), kb = Object.keys(b);
+  if (ka.length !== kb.length) return false;
+  for (var j = 0; j < ka.length; j++) { if (!Object.prototype.hasOwnProperty.call(b, ka[j]) || !_deepEqual(a[ka[j]], b[ka[j]])) return false; }
+  return true;
+}
+
+function _equals(a, b) {
+  var aN = a === NOTHING, bN = b === NOTHING;
+  if (aN || bN) return aN && bN;                             // Nothing equals only Nothing
+  return _deepEqual(a, b);
+}
+// Strict ordering "a < b": defined only for two numbers or two strings
+// (RFC 9535 §2.3.5.2.2); anything else (incl. Nothing) is not <.
+function _less(a, b) {
+  if (a === NOTHING || b === NOTHING) return false;
+  var comparable = (typeof a === "number" && typeof b === "number") || (typeof a === "string" && typeof b === "string");
+  if (!comparable) return false;
+  return a < b;
+}
+function _compare(op, a, b) {
+  switch (op) {
+    case "==": return _equals(a, b);
+    case "!=": return !_equals(a, b);
+    case "<":  return _less(a, b);
+    case ">":  return _less(b, a);
+    case "<=": return _less(a, b) || _equals(a, b);          // §2.3.5.2.2: <= is < OR ==
+    case ">=": return _less(b, a) || _equals(a, b);
+    default:   return false;
+  }
+}
+
+function _truthy(x) { return x === true; }
+
+function _evalLogical(node, current, root) {
+  switch (node.type) {
+    case "or": return _evalLogical(node.a, current, root) || _evalLogical(node.b, current, root);
+    case "and": return _evalLogical(node.a, current, root) && _evalLogical(node.b, current, root);
+    case "not": return !_evalLogical(node.e, current, root);
+    case "compare": return _compare(node.op, _evalComparable(node.a, current, root), _evalComparable(node.b, current, root));
+    case "query": return _queryNodes(node, current, root).length > 0;       // existence test
+    case "func": return _evalFunctionLogical(node, current, root);
+    default: return false;
+  }
+}
+
+// --- standard functions ---
+function _funcArgValue(arg, current, root) {
+  if (arg.type === "lit") return arg.value;
+  if (arg.type === "query") return _singularValue(arg, current, root);   // ValueType from singular query
+  if (arg.type === "func") return _evalFunctionValue(arg, current, root);
+  return NOTHING;
+}
+function _funcArgNodes(arg, current, root) {
+  if (arg.type === "query") return _queryNodes(arg, current, root);
+  if (arg.type === "func") { var v = _evalFunctionValue(arg, current, root); return v === NOTHING ? [] : [{ value: v, path: [] }]; }
+  return [];
+}
+
+function _evalFunctionValue(node, current, root) {
+  if (node.name === "length") {
+    var v = _funcArgValue(node.args[0], current, root);
+    if (v === NOTHING) return NOTHING;                       // length(Nothing) = Nothing (the sentinel is itself an object)
+    if (typeof v === "string") return Array.from(v).length;
+    if (Array.isArray(v)) return v.length;
+    if (_isObject(v)) return Object.keys(v).length;
+    return NOTHING;
+  }
+  if (node.name === "count") return _funcArgNodes(node.args[0], current, root).length;
+  if (node.name === "value") { var ns = _funcArgNodes(node.args[0], current, root); return ns.length === 1 ? ns[0].value : NOTHING; }
+  return NOTHING;
+}
+
+function _iRegexpToJs(pattern, anchored) {
+  // I-Regexp (RFC 9485) is close to a JS regex subset. Translate the one
+  // systematic difference — "." must not match line separators — and
+  // (for match) anchor the whole input.
+  var translated = pattern.replace(/(\\.)|(\[(?:\\.|[^\]\\])*\])|\./g, function (m, esc, cls) {
+    if (esc) return esc;
+    if (cls) return cls;
+    return "[^\\n\\r]";
+  });
+  // The pattern is the I-Regexp argument of an RFC 9535 match()/search()
+  // filter — translated (not raw) and used only as a boolean test.
+  return new RegExp(anchored ? "^(?:" + translated + ")$" : translated, "su");   // allow:dynamic-regex — translated I-Regexp from a match()/search() filter argument
+}
+function _evalFunctionLogical(node, current, root) {
+  var input = _funcArgValue(node.args[0], current, root);
+  var pat = _funcArgValue(node.args[1], current, root);
+  if (typeof input !== "string" || typeof pat !== "string") return false;
+  var re;
+  try { re = _iRegexpToJs(pat, node.name === "match"); } catch (_e) { return false; }
+  return re.test(input);
+}
+
+/**
+ * @primitive b.jsonPath.query
+ * @signature b.jsonPath.query(doc, path)
+ * @since     0.12.61
+ * @status    stable
+ * @compliance soc2
+ * @related   b.jsonPath.paths, b.guardJsonPath.gate
+ *
+ * Evaluate an RFC 9535 JSONPath query against a JSON value and return the
+ * array of matched node values (the nodelist, in document order). The
+ * full path language is supported — name / wildcard / index / slice
+ * selectors, descendant segments (<code>..</code>), and filter
+ * selectors (<code>?</code>) with comparisons, <code>&&</code> /
+ * <code>||</code> / <code>!</code>, relative (<code>@</code>) and
+ * absolute (<code>$</code>) queries, and the functions
+ * <code>length</code> / <code>count</code> / <code>match</code> /
+ * <code>search</code> / <code>value</code>. A malformed or ill-typed
+ * query throws <code>json-path/invalid</code>.
+ *
+ * @example
+ *   b.jsonPath.query({ a: [{ p: 1 }, { p: 9 }] }, "$.a[?@.p > 5].p");
+ *   // → [9]
+ */
+function query(doc, path) {
+  var ast = _parse(path);
+  return _evalSegments(ast.segments, doc).map(function (n) { return n.value; });
+}
+
+function _normalizedPath(tokens) {
+  var out = "$";
+  for (var i = 0; i < tokens.length; i++) {
+    var t = tokens[i];
+    if (typeof t === "number") out += "[" + t + "]";
+    else out += "['" + String(t).replace(/\\/g, "\\\\").replace(/'/g, "\\'") + "']";
+  }
+  return out;
+}
+
+/**
+ * @primitive b.jsonPath.paths
+ * @signature b.jsonPath.paths(doc, path)
+ * @since     0.12.61
+ * @status    stable
+ * @related   b.jsonPath.query
+ *
+ * Like <code>query</code>, but returns the normalized-path location of
+ * each match (RFC 9535 §2.7 normalized paths, e.g.
+ * <code>$['a'][1]['p']</code>) instead of the values — useful for
+ * reporting or for building a follow-up patch.
+ *
+ * @example
+ *   b.jsonPath.paths({ a: [{ p: 1 }, { p: 9 }] }, "$.a[?@.p > 5].p");
+ *   // → ["$['a'][1]['p']"]
+ */
+function paths(doc, path) {
+  var ast = _parse(path);
+  return _evalSegments(ast.segments, doc).map(function (n) { return _normalizedPath(n.path); });
+}
+
+module.exports = {
+  query:         query,
+  paths:         paths,
+  JsonPathError: JsonPathError,
+};

package/lib/jtd.js

@@ -0,0 +1,234 @@
+"use strict";
+/**
+ * @module b.jtd
+ * @nav    Data
+ * @title  JSON Type Definition
+ *
+ * @intro
+ *   Validate a JSON value against a JSON Type Definition schema (RFC
+ *   8927) — a small, portable, cross-implementation schema language.
+ *   Unlike the framework's fluent <code>b.safeSchema</code> builder, a
+ *   JTD schema is plain JSON you can share with any JTD implementation
+ *   (and generate code from), which makes it the right choice for
+ *   interop contracts.
+ *
+ *   <code>validate(schema, instance)</code> returns an array of errors,
+ *   each a <code>{ instancePath, schemaPath }</code> pair pointing at the
+ *   offending value and the schema rule it broke (an empty array means
+ *   valid). All eight schema forms are supported — empty, <code>type</code>,
+ *   <code>enum</code>, <code>elements</code>, <code>properties</code>,
+ *   <code>values</code>, <code>discriminator</code>, and <code>ref</code>
+ *   (with <code>definitions</code>) — and a malformed schema is rejected
+ *   at compile time rather than mis-validating.
+ *
+ * @card
+ *   JSON Type Definition (RFC 8927) — validate JSON against a portable,
+ *   standardized schema (all eight forms), returning instancePath /
+ *   schemaPath errors. The interop-friendly companion to the fluent
+ *   <code>b.safeSchema</code> builder.
+ */
+
+var { defineClass } = require("./framework-error");
+
+var JtdError = defineClass("JtdError", { alwaysPermanent: true });
+
+var MAX_DEPTH = 10000;                                       // allow:raw-time-literal — recursion cap for self-referential refs
+
+var TYPES = {
+  boolean: 1, string: 1, timestamp: 1, float32: 1, float64: 1,
+  int8: 1, uint8: 1, int16: 1, uint16: 1, int32: 1, uint32: 1,
+};
+var INT_RANGES = {
+  int8: [-128, 127], uint8: [0, 255], int16: [-32768, 32767],                              // allow:raw-byte-literal — RFC 8927 integer type bounds
+  uint16: [0, 65535], int32: [-2147483648, 2147483647], uint32: [0, 4294967295],            // allow:raw-byte-literal — RFC 8927 integer type bounds
+};
+var FORM_KEYWORDS = ["ref", "type", "enum", "elements", "properties", "optionalProperties", "values", "discriminator"];
+var SHARED_KEYWORDS = { definitions: 1, nullable: 1, metadata: 1 };
+
+function _isPlainObject(v) { return v !== null && typeof v === "object" && !Array.isArray(v); }
+function _isInteger(v) { return typeof v === "number" && isFinite(v) && Math.floor(v) === v; }
+
+// RFC 3339 date-time (the JTD "timestamp" type).
+var RFC3339 = /^(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(\.\d+)?([Zz]|[+-]\d{2}:\d{2})$/;
+function _validTimestamp(s) {
+  var m = RFC3339.exec(s);
+  if (!m) return false;
+  var mo = +m[2], d = +m[3], h = +m[4], mi = +m[5], se = +m[6];
+  if (mo < 1 || mo > 12 || d < 1 || d > 31 || h > 23 || mi > 59 || se > 60) return false;   // allow:raw-time-literal — RFC 3339 field ranges (60 = leap second)
+  var days = [31, ((+m[1] % 4 === 0 && +m[1] % 100 !== 0) || +m[1] % 400 === 0) ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];   // allow:raw-time-literal — days per month
+  if (d > days[mo - 1]) return false;
+  var tz = m[8];
+  if (tz !== "Z" && tz !== "z") {                            // numeric offset must be in range
+    if (+tz.slice(1, 3) > 23 || +tz.slice(4, 6) > 59) return false;   // allow:raw-time-literal — RFC 3339 offset hour/minute ranges
+  }
+  return true;
+}
+
+// --- compile-time well-formedness (RFC 8927 section 2.2) ---
+function _checkSchema(schema, root, isRoot) {
+  if (!_isPlainObject(schema)) throw new JtdError("jtd/bad-schema", "jtd: schema must be an object");
+  if (!isRoot && Object.prototype.hasOwnProperty.call(schema, "definitions")) throw new JtdError("jtd/bad-schema", "jtd: 'definitions' is allowed only at the root");
+  Object.keys(schema).forEach(function (k) {
+    if (FORM_KEYWORDS.indexOf(k) === -1 && !SHARED_KEYWORDS[k] && k !== "additionalProperties" && k !== "mapping") throw new JtdError("jtd/bad-schema", "jtd: unknown keyword '" + k + "'");
+  });
+  if (Object.prototype.hasOwnProperty.call(schema, "nullable") && typeof schema.nullable !== "boolean") throw new JtdError("jtd/bad-schema", "jtd: 'nullable' must be a boolean");
+  if (Object.prototype.hasOwnProperty.call(schema, "metadata") && !_isPlainObject(schema.metadata)) throw new JtdError("jtd/bad-schema", "jtd: 'metadata' must be an object");
+  if (Object.prototype.hasOwnProperty.call(schema, "definitions")) {
+    if (!_isPlainObject(schema.definitions)) throw new JtdError("jtd/bad-schema", "jtd: 'definitions' must be an object");
+    Object.keys(schema.definitions).forEach(function (k) { _checkSchema(schema.definitions[k], root, false); });
+  }
+  if (Object.prototype.hasOwnProperty.call(schema, "mapping") && !Object.prototype.hasOwnProperty.call(schema, "discriminator")) throw new JtdError("jtd/bad-schema", "jtd: 'mapping' is only valid with 'discriminator'");
+  var formSet = {};
+  FORM_KEYWORDS.forEach(function (k) { if (Object.prototype.hasOwnProperty.call(schema, k)) formSet[(k === "optionalProperties") ? "properties" : k] = 1; });
+  var formNames = Object.keys(formSet);
+  if (formNames.length > 1) throw new JtdError("jtd/bad-schema", "jtd: a schema may use only one form (got " + formNames.join(", ") + ")");
+
+  if ("ref" in schema) {
+    if (typeof schema.ref !== "string" || !root.definitions || !Object.prototype.hasOwnProperty.call(root.definitions, schema.ref)) throw new JtdError("jtd/bad-schema", "jtd: 'ref' must name a key in the root definitions");
+  }
+  if ("type" in schema && !TYPES[schema.type]) throw new JtdError("jtd/bad-schema", "jtd: unknown type '" + schema.type + "'");
+  if ("enum" in schema) {
+    if (!Array.isArray(schema.enum) || schema.enum.length === 0) throw new JtdError("jtd/bad-schema", "jtd: 'enum' must be a non-empty array");
+    var seen = Object.create(null);
+    schema.enum.forEach(function (e) { if (typeof e !== "string") throw new JtdError("jtd/bad-schema", "jtd: 'enum' values must be strings"); if (seen[e]) throw new JtdError("jtd/bad-schema", "jtd: duplicate enum value"); seen[e] = 1; });
+  }
+  if ("elements" in schema) _checkSchema(schema.elements, root, false);
+  if ("values" in schema) _checkSchema(schema.values, root, false);
+  if ("properties" in schema || "optionalProperties" in schema) {
+    var props = schema.properties || {}, opt = schema.optionalProperties || {};
+    if (!_isPlainObject(props) || !_isPlainObject(opt)) throw new JtdError("jtd/bad-schema", "jtd: properties / optionalProperties must be objects");
+    Object.keys(props).forEach(function (k) { if (Object.prototype.hasOwnProperty.call(opt, k)) throw new JtdError("jtd/bad-schema", "jtd: '" + k + "' in both properties and optionalProperties"); _checkSchema(props[k], root, false); });
+    Object.keys(opt).forEach(function (k) { _checkSchema(opt[k], root, false); });
+    if ("additionalProperties" in schema && typeof schema.additionalProperties !== "boolean") throw new JtdError("jtd/bad-schema", "jtd: 'additionalProperties' must be a boolean");
+  }
+  if ("discriminator" in schema) {
+    if (typeof schema.discriminator !== "string") throw new JtdError("jtd/bad-schema", "jtd: 'discriminator' must be a string");
+    if (!_isPlainObject(schema.mapping)) throw new JtdError("jtd/bad-schema", "jtd: 'discriminator' requires a 'mapping' object");
+    Object.keys(schema.mapping).forEach(function (k) {
+      var sub = schema.mapping[k];
+      _checkSchema(sub, root, false);
+      if (!_isPlainObject(sub) || (!("properties" in sub) && !("optionalProperties" in sub))) throw new JtdError("jtd/bad-schema", "jtd: discriminator mapping schemas must use the properties form");
+      if (sub.nullable === true) throw new JtdError("jtd/bad-schema", "jtd: discriminator mapping schemas must not be nullable");
+      var p = sub.properties || {}, o = sub.optionalProperties || {};
+      if (Object.prototype.hasOwnProperty.call(p, schema.discriminator) || Object.prototype.hasOwnProperty.call(o, schema.discriminator)) throw new JtdError("jtd/bad-schema", "jtd: discriminator tag must not appear in a mapping schema's properties");
+    });
+  }
+  if ("additionalProperties" in schema && !("properties" in schema) && !("optionalProperties" in schema)) throw new JtdError("jtd/bad-schema", "jtd: 'additionalProperties' requires a properties form");
+}
+
+// --- validation (RFC 8927 section 3.3) ---
+function _typeOk(type, v) {
+  if (type === "boolean") return typeof v === "boolean";
+  if (type === "string") return typeof v === "string";
+  if (type === "timestamp") return typeof v === "string" && _validTimestamp(v);
+  if (type === "float32" || type === "float64") return typeof v === "number" && isFinite(v);
+  var range = INT_RANGES[type];
+  return _isInteger(v) && v >= range[0] && v <= range[1];
+}
+
+function _val(schema, inst, ip, sp, root, depth, errors, discrimTag) {
+  if (depth > MAX_DEPTH) throw new JtdError("jtd/too-deep", "jtd: schema recursion exceeded the depth cap");
+  if (schema.nullable === true && inst === null) return;
+
+  if ("ref" in schema) { _val(root.definitions[schema.ref], inst, ip, ["definitions", schema.ref], root, depth + 1, errors, undefined); return; }
+
+  if ("type" in schema) {
+    if (!_typeOk(schema.type, inst)) errors.push({ instancePath: ip.slice(), schemaPath: sp.concat("type") });
+    return;
+  }
+  if ("enum" in schema) {
+    if (typeof inst !== "string" || schema.enum.indexOf(inst) === -1) errors.push({ instancePath: ip.slice(), schemaPath: sp.concat("enum") });
+    return;
+  }
+  if ("elements" in schema) {
+    if (!Array.isArray(inst)) { errors.push({ instancePath: ip.slice(), schemaPath: sp.concat("elements") }); return; }
+    for (var i = 0; i < inst.length; i++) _val(schema.elements, inst[i], ip.concat(String(i)), sp.concat("elements"), root, depth + 1, errors, undefined);
+    return;
+  }
+  if ("properties" in schema || "optionalProperties" in schema) {
+    if (!_isPlainObject(inst)) {
+      errors.push({ instancePath: ip.slice(), schemaPath: sp.concat("properties" in schema ? "properties" : "optionalProperties") });
+      return;
+    }
+    var props = schema.properties || {}, opt = schema.optionalProperties || {};
+    Object.keys(props).forEach(function (k) {
+      if (Object.prototype.hasOwnProperty.call(inst, k)) _val(props[k], inst[k], ip.concat(k), sp.concat("properties", k), root, depth + 1, errors, undefined);
+      else errors.push({ instancePath: ip.slice(), schemaPath: sp.concat("properties", k) });
+    });
+    Object.keys(opt).forEach(function (k) {
+      if (Object.prototype.hasOwnProperty.call(inst, k)) _val(opt[k], inst[k], ip.concat(k), sp.concat("optionalProperties", k), root, depth + 1, errors, undefined);
+    });
+    if (schema.additionalProperties !== true) {
+      Object.keys(inst).forEach(function (k) {
+        if (!Object.prototype.hasOwnProperty.call(props, k) && !Object.prototype.hasOwnProperty.call(opt, k) && k !== discrimTag) {
+          errors.push({ instancePath: ip.concat(k), schemaPath: sp.slice() });
+        }
+      });
+    }
+    return;
+  }
+  if ("values" in schema) {
+    if (!_isPlainObject(inst)) { errors.push({ instancePath: ip.slice(), schemaPath: sp.concat("values") }); return; }
+    Object.keys(inst).forEach(function (k) { _val(schema.values, inst[k], ip.concat(k), sp.concat("values"), root, depth + 1, errors, undefined); });
+    return;
+  }
+  if ("discriminator" in schema) {
+    if (!_isPlainObject(inst)) { errors.push({ instancePath: ip.slice(), schemaPath: sp.concat("discriminator") }); return; }
+    var tag = schema.discriminator;
+    if (!Object.prototype.hasOwnProperty.call(inst, tag)) { errors.push({ instancePath: ip.slice(), schemaPath: sp.concat("discriminator") }); return; }
+    if (typeof inst[tag] !== "string") { errors.push({ instancePath: ip.concat(tag), schemaPath: sp.concat("discriminator") }); return; }
+    if (!Object.prototype.hasOwnProperty.call(schema.mapping, inst[tag])) { errors.push({ instancePath: ip.concat(tag), schemaPath: sp.concat("mapping") }); return; }
+    _val(schema.mapping[inst[tag]], inst, ip, sp.concat("mapping", inst[tag]), root, depth + 1, errors, tag);
+    return;
+  }
+  // empty form: accepts anything
+}
+
+/**
+ * @primitive b.jtd.validate
+ * @signature b.jtd.validate(schema, instance)
+ * @since     0.12.62
+ * @status    stable
+ * @compliance soc2
+ * @related   b.safeSchema, b.jsonPointer.get
+ *
+ * Validate a JSON value against a JSON Type Definition schema (RFC 8927)
+ * and return the array of validation errors — each a
+ * <code>{ instancePath, schemaPath }</code> pair of token arrays naming
+ * the offending value and the schema rule it broke. An empty array means
+ * the instance is valid. All eight schema forms are supported. The schema
+ * itself is checked for well-formedness first; a malformed schema throws
+ * <code>jtd/bad-schema</code> rather than silently mis-validating.
+ *
+ * @example
+ *   b.jtd.validate({ properties: { id: { type: "uint32" } } }, { id: -1 });
+ *   // -> [ { instancePath: ["id"], schemaPath: ["properties", "id", "type"] } ]
+ */
+function validate(schema, instance) {
+  _checkSchema(schema, schema, true);
+  var errors = [];
+  _val(schema, instance, [], [], schema, 0, errors, undefined);
+  return errors;
+}
+
+/**
+ * @primitive b.jtd.isValid
+ * @signature b.jtd.isValid(schema, instance)
+ * @since     0.12.62
+ * @status    stable
+ * @related   b.jtd.validate
+ *
+ * Convenience boolean form of <code>validate</code> — <code>true</code>
+ * when the instance conforms to the JTD schema (no errors). Throws
+ * <code>jtd/bad-schema</code> on a malformed schema.
+ *
+ * @example
+ *   b.jtd.isValid({ type: "string" }, "hello");   // -> true
+ */
+function isValid(schema, instance) { return validate(schema, instance).length === 0; }
+
+module.exports = {
+  validate: validate,
+  isValid:  isValid,
+  JtdError: JtdError,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.60",
+  "version": "0.12.62",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:1329fa76-6890-4008-be5d-6db27e71506c",
+  "serialNumber": "urn:uuid:f56710ee-2e4e-4c8e-af88-80f79561870e",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-26T01:30:30.570Z",
+    "timestamp": "2026-05-26T03:54:31.896Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.60",
+      "bom-ref": "@blamejs/core@0.12.62",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.60",
+      "version": "0.12.62",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.60",
+      "purl": "pkg:npm/%40blamejs/core@0.12.62",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.60",
+      "ref": "@blamejs/core@0.12.62",
       "dependsOn": []
     }
   ]