@jarenjs/db 0.49.2 → 0.56.0

package/src/model.js

@@ -24,6 +24,7 @@
 import {
   collectSameDocumentAnchors, resolveSameDocumentRef,
 } from '@jarenjs/validate/normalize';
+import { compileJsonQuery } from '@jarenjs/json/query';
 
 import { DbCompileError } from './errors.js';
 
@@ -123,12 +124,65 @@ function checkDefault(declared, docPath) {
     || declared === 'auto') return;
   if (declared !== null && typeof declared === 'object' && !Array.isArray(declared)
     && (Object.hasOwn(declared, 'value') !== Object.hasOwn(declared, 'query'))
-    && Object.keys(declared).length === 1) return;
+    && Object.keys(declared).length === 1) {
+    if (Object.hasOwn(declared, 'query')) {
+      // compiled where the model is checked, not at the first
+      // `store.entity()` call — a default that cannot compile is a model
+      // defect, and the engine's reason travels with the model position
+      try {
+        compileJsonQuery(declared.query);
+      }
+      catch (cause) {
+        throw new DbCompileError('JD0005',
+          `the { query } default does not compile: ${/** @type {Error} */ (cause).message}`,
+          docPath, /** @type {Error} */ (cause));
+      }
+    }
+    return;
+  }
   throw modelError(
     "a default is 'now', 'updated', 'uuid', 'auto', { value: … } or { query: … }",
     docPath);
 }
 
+/** The schema positions whose `x-entity` block the one-level walk READS:
+ * a top-level property, an `allOf` branch of one (shallow-merged), and
+ * a `$defs`/anchor target (a property's `$ref` resolves there). */
+const READ_BLOCK_KEYS = new Set(['allOf', '$defs', 'definitions']);
+
+/**
+ * Find an `x-entity` block the entity walk would never read — nested
+ * inside a property's `properties`, `items`, `anyOf`, … — so it fails
+ * the model instead of being ignored. §9.2's promise: a silently
+ * ignored mapping directive is a data-loss bug, so the vocabulary is
+ * closed in POSITION as well as in name.
+ * @param {any} node
+ * @param {string} path
+ * @param {boolean} read - whether a block AT this node is read
+ * @returns {string | null} the docPath of an unread block
+ */
+function unreadEntityBlock(node, path, read) {
+  if (node === null || typeof node !== 'object') return null;
+  if (Array.isArray(node)) {
+    for (let i = 0; i < node.length; i++) {
+      const found = unreadEntityBlock(node[i], `${path}/${i}`, read);
+      if (found !== null) return found;
+    }
+    return null;
+  }
+  for (const key of Object.keys(node)) {
+    if (key === 'x-entity') {
+      if (!read) return `${path}/x-entity`;
+      continue;
+    }
+    // a block one level under a read position is read only through
+    // `allOf`/`$defs`; under anything else it is out of the walk
+    const found = unreadEntityBlock(node[key], `${path}/${key}`, read && READ_BLOCK_KEYS.has(key));
+    if (found !== null) return found;
+  }
+  return null;
+}
+
 /**
  * Normalize the `entities` member of a model document.
  * @param {any} model
@@ -169,14 +223,54 @@ export function normalizeEntities(model) {
           ? raw['x-entity'] : undefined),
         `${propertyPath}/x-entity`);
 
-      const type = typeof effective.type === 'string'
-        ? effective.type
-        : Array.isArray(effective.type)
-          ? effective.type.find((t) => t !== 'null')
-          : undefined;
+      // a nullable scalar (`['string', 'null']`) is that scalar; a union
+      // of two or more scalar types has no one column type and lives in
+      // the document (§9.3) — mapping it by its FIRST member stored `5`
+      // as `"5.0"` in a text column
+      const scalarMembers = Array.isArray(effective.type)
+        ? effective.type.filter((t) => t !== 'null')
+        : [effective.type];
+      const type = scalarMembers.length === 1 && typeof scalarMembers[0] === 'string'
+        ? scalarMembers[0]
+        : undefined;
+      const union = scalarMembers.length > 1;
 
       if (entityBlock.default !== undefined)
         checkDefault(entityBlock.default, `${propertyPath}/x-entity/default`);
+      if (entityBlock.default !== undefined && entityBlock.relation !== undefined) {
+        throw modelError('a relation member takes no default — it is a projection, not stored state',
+          `${propertyPath}/x-entity/default`);
+      }
+      if (entityBlock.default === 'auto' && entityBlock.key !== true) {
+        throw modelError("default: 'auto' is allocated by the database for a single integer key only",
+          `${propertyPath}/x-entity/default`);
+      }
+      // the mapping directives that need a column of their own: on a
+      // property the document keeps — `column: 'json'`, a non-scalar, a
+      // union — they were accepted and never applied (a key with no key
+      // column let duplicates in and broke every read)
+      const columnMapped = SCALARS.has(type ?? '') && entityBlock.column !== 'json';
+      const needsColumn = ['key', 'unique', 'index'].filter((member) => entityBlock[member] === true);
+      if (!columnMapped && needsColumn.length > 0) {
+        const why = entityBlock.column === 'json'
+          ? "column: 'json' keeps the property in the document"
+          : union ? 'a union of scalar types lives in the document'
+            : 'only a top-level scalar takes a column';
+        throw modelError(entityBlock.key === true
+          ? `a key property must be a scalar with a column of its own — ${why}`
+          : `'${propertyName}' declares ${needsColumn.join('/')} but has no column — ${why}`,
+          propertyPath);
+      }
+      for (const key of Object.keys(raw !== null && typeof raw === 'object' ? raw : {})) {
+        if (key === 'x-entity') continue;
+        const unread = unreadEntityBlock(raw[key], `${propertyPath}/${key}`, READ_BLOCK_KEYS.has(key));
+        if (unread !== null) {
+          throw new DbCompileError('JD0030',
+            'x-entity applies to an entity\'s top-level properties (and their allOf/$ref '
+            + 'targets) only — a nested block is never read, so it is refused rather than ignored',
+            unread);
+        }
+      }
       if (entityBlock.column !== undefined
         && entityBlock.column !== 'integer' && entityBlock.column !== 'json') {
         throw modelError("x-entity.column is 'integer' (epoch date column) or 'json' (stay in the document)",
@@ -289,6 +383,16 @@ function resolveRelations(entities) {
       // many-to-many: a join table
       relation.kind = 'manyToMany';
       const other = relation.to;
+      if (other === owner) {
+        throw modelError('a many-to-many relation to the entity itself is not supported — '
+          + 'both endpoint columns would carry the same name', docPath);
+      }
+      for (const endpoint of [owner, other]) {
+        if (entities.get(endpoint).keys.length !== 1) {
+          throw modelError(`a many-to-many relation needs single-key endpoints; '${endpoint}' `
+            + 'declares a composite key', docPath);
+        }
+      }
       relation.joinTable = typeof relation.through === 'string'
         ? relation.through
         : [owner, other].sort().join('_');
@@ -313,6 +417,13 @@ function resolveRelations(entities) {
     const holder = entities.get(relation.fkEntity);
     const declaredVia = holder.properties.get(relation.via);
     const targetEntity = entities.get(relation.fkTargets);
+    if (targetEntity.keys.length !== 1) {
+      // a foreign key references ONE column; a composite-key target
+      // rendered a reference to its first key alone, which SQLite
+      // refused at the first write with a raw "foreign key mismatch"
+      throw modelError(`a foreign-key relation must reference a single-key entity; `
+        + `'${relation.fkTargets}' declares a composite key`, docPath);
+    }
     const targetKeyType = targetEntity.properties.get(targetEntity.keys[0]).type;
     if (declaredVia !== undefined) {
       if (declaredVia.type !== targetKeyType || declaredVia.column === 'json') {
@@ -355,7 +466,8 @@ function resolveRelations(entities) {
         if (relationA.kind !== relationB.kind) {
           throw new DbCompileError('JD0031',
             `relation '${a.owner}.${a.property.name}' and '${b.owner}.${b.property.name}' `
-            + `disagree on the foreign key ('${relationA.via}' vs '${relationB.via}')`,
+            + `disagree on the foreign key ('${relationA.via}' vs '${relationB.via}') `
+            + '— two edges between the same pair declare their inverse on one side only (§9.4)',
             `${a.property.docPath}/x-entity/relation`);
         }
         continue;
@@ -377,6 +489,53 @@ function resolveRelations(entities) {
   }
 }
 
+/**
+ * The relation table a producer may read (§10.1): per entity, one
+ * frozen record per declared relation member — `to`, `kind`, and for a
+ * foreign-key relation `via`, `fkEntity`, `fkTargets` and `targetKey`
+ * (the key property the foreign key references on `fkTargets`, which
+ * is what a hop's equality compares `via` against); for a many-to-many
+ * `joinTable` and the target's `targetKey`. Plain data, keyed by
+ * entity name and then by member name, so a query producer can lower
+ * a relation hop to the phrases the translator runs without a second
+ * vocabulary and without importing this package.
+ * @param {Map<string, any>} entities - normalized entities
+ * @returns {Readonly<Record<string, Readonly<Record<string, any>>>>}
+ */
+export function relationTables(entities) {
+  /** @type {Record<string, any>} */
+  const tables = {};
+  for (const entity of entities.values()) {
+    /** @type {Record<string, any>} */
+    const table = {};
+    for (const property of entity.relations) {
+      const relation = property.relation;
+      const entry = relation.kind === 'manyToMany'
+        ? {
+          to: relation.to,
+          kind: relation.kind,
+          joinTable: relation.joinTable,
+          targetKey: entities.get(relation.to).keys[0],
+        }
+        : {
+          to: relation.to,
+          kind: relation.kind,
+          via: relation.via,
+          fkEntity: relation.fkEntity,
+          fkTargets: relation.fkTargets,
+          targetKey: entities.get(relation.fkTargets).keys[0],
+        };
+      // an own member, whatever the property is named: `__proto__` as
+      // a member name would otherwise rewrite the record's prototype
+      Object.defineProperty(table, property.name,
+        { value: Object.freeze(entry), writable: true, enumerable: true, configurable: true });
+    }
+    Object.defineProperty(tables, entity.name,
+      { value: Object.freeze(table), writable: true, enumerable: true, configurable: true });
+  }
+  return Object.freeze(tables);
+}
+
 /**
  * The hybrid mapping, derived mechanically from §9.3's table and
  * returned as DATA: per entity, the columns (name, type, source),
@@ -408,7 +567,13 @@ export function explainMapping(model) {
         source: epoch ? 'epoch(document)' : 'document',
         key: property.key,
       };
-      if (property.enum !== undefined) column.check = property.enum;
+      if (property.enum !== undefined) {
+        // `null` never fails a CHECK (NULL IN (…) is unknown, which
+        // passes), but rendered into the list it made the whole CHECK
+        // unknown for EVERY value — a nullable enum accepted anything
+        const values = property.enum.filter((value) => value !== null);
+        if (values.length > 0) column.check = values;
+      }
       columns.push(column);
       if (property.unique) indexes.push({ property: property.name, unique: true });
       else if (property.index) indexes.push({ property: property.name, unique: false });

package/src/plan.js

@@ -45,7 +45,7 @@ import { compileBuckets, resampleSeries, toEpoch } from '@jarenjs/core/series';
 
 import { selectPlan, conjoin, PLAN_VERSION } from './algebra.js';
 import { typeOfPath, isNumericType } from './types.js';
-import { schemaNodeAt } from './ddl.js';
+import { schemaNodeAt, canonicalOf } from './ddl.js';
 import {
   BBOX_COMPONENTS, BBOX_INDEX_ORDER, PRECISION_MIN, PRECISION_MAX,
   probeBox, probePosition, probeCircleBox, cellNeighbourhood, probeVector,
@@ -125,6 +125,31 @@ for (const kind of NODE_KINDS) {
  * @param {string} reason
  * @returns {{ construct: string, reason: string }}
  */
+/** Whether a literal window bound is one SQL takes as written: a
+ * non-negative safe integer. A negative, fractional or non-finite bound
+ * is the ENGINE's to interpret (it answers `[]`, a truncation or a
+ * refusal), and interpolated into `LIMIT`/`OFFSET` it answered other
+ * rows or a raw database error. */
+function isWindowBound(value) {
+  return Number.isSafeInteger(value) && value >= 0;
+}
+
+/** Whether a schema node admits `null` beside its scalar type. A present
+ * null orders and aggregates in SQL (NULLS FIRST, skipped by SUM) where
+ * the engine refuses it (`JQ2005`, `JQ2001`), so a promotion over such a
+ * path answers where the reference semantics throw. */
+function admitsNull(schema, segments) {
+  const node = schemaNodeAt(schema, segments);
+  return Array.isArray(node?.type) && node.type.includes('null');
+}
+
+/** Whether a typed reference orders natively: numbers and strings that
+ * cannot hold a null. A boolean orders as 0/1 in SQL and is `JQ2005` in
+ * the engine. */
+function orderable(ref, schema) {
+  return ref.type !== 'unknown' && ref.type !== 'boolean' && !admitsNull(schema, ref.segments);
+}
+
 function refusal(construct, reason) {
   return { construct, reason };
 }
@@ -268,9 +293,7 @@ function memberPath(node, itSlot) {
     else return null;
   }
   if (segments.length === 0) return null;
-  const canonical = segments
-    .map((s) => ('name' in s ? `.${s.name}` : `[${s.index}]`)).join('');
-  return { segments, canonical };
+  return { segments, canonical: canonicalOf(segments) };
 }
 
 /**
@@ -634,6 +657,10 @@ function planDistanceBound(node, itSlot, shape) {
   if (constant === null) return { refusal: refusal('$distance', SPATIAL_REASONS.operand) };
   const at = probePosition(constant.value);
   if (at === null) return { refusal: refusal('$distance', SPATIAL_REASONS.unbounded) };
+  if (!Number.isFinite(radius.value) || radius.value < 0) {
+    return { refusal: refusal('$distance',
+      'a distance bound is a finite, non-negative number of metres') };
+  }
   const box = probeCircleBox(at, radius.value);
   if (box === null) return { refusal: refusal('$distance', SPATIAL_REASONS.pole) };
   if (box[0] < -180 || box[2] > 180)
@@ -1046,13 +1073,30 @@ function planPredicate(node, itSlot, shape) {
 // and it is why a calendar ladder, a fill policy, a rolling window and
 // an as-of JOIN cost a bounded fetch rather than a wrong answer.
 
-/** Is this node the whole collection — `$[*]` over the input document? */
+/**
+ * The source a packed spelling stands for. `["$[*]"]` — an array
+ * constructor of exactly one element — is what a `$for` unpacks back
+ * into the rows (QUERY-FORMAT §6.2, D4): `@jarenjs/linq` binds every
+ * iterated source that way so an array-valued ROW stays one item. Over
+ * a collection or an entity array the rows are objects, so the packed
+ * and the bare spelling are the same rows, and the planner reads
+ * through the packing rather than sending the document to the residual.
+ * @param {any} node
+ * @returns {any}
+ */
+function unpacked(node) {
+  return node?.kind === 'array' && node.elements?.length === 1 ? node.elements[0] : node;
+}
+
+/** Is this node the whole collection — `$[*]` over the input document,
+ * bare or packed? */
 function isCollectionSource(node) {
-  return node?.kind === 'path' && node.name === '$' && node.external !== true
-    && node.rootSlot === 0 && node.singular !== true
-    && node.segments.length === 1 && node.segments[0].descendant !== true
-    && node.segments[0].selectors.length === 1
-    && node.segments[0].selectors[0].kind === 'wildcard';
+  const path = unpacked(node);
+  return path?.kind === 'path' && path.name === '$' && path.external !== true
+    && path.rootSlot === 0 && path.singular !== true
+    && path.segments.length === 1 && path.segments[0].descendant !== true
+    && path.segments[0].selectors.length === 1
+    && path.segments[0].selectors[0].kind === 'wildcard';
 }
 
 /**
@@ -1081,7 +1125,7 @@ function memberRef(shape, name) {
   return {
     segments,
     type: typeOfPath(shape.schema, segments),
-    column: shape.columnByCanonical.get(`.${name}`) ?? null,
+    column: shape.columnByCanonical.get(canonicalOf(segments)) ?? null,
   };
 }
 
@@ -1643,13 +1687,10 @@ function planFlwor(node, shape, rawFlwor, udfHook) {
   const plan = selectPlan(shape.collection);
 
   // the one recognised source shape: a single plain binding over $[*]
+  // (bare or packed — one check, `isCollectionSource`, for every site)
   const binding = node.forBindings[0];
-  const source = binding?.expr;
   const sourceIsCollection = node.forBindings.length === 1
-    && source?.kind === 'path' && source.name === '$' && source.external !== true
-    && source.segments.length === 1 && source.segments[0].descendant !== true
-    && source.segments[0].selectors.length === 1
-    && source.segments[0].selectors[0].kind === 'wildcard'
+    && isCollectionSource(binding?.expr)
     && binding.window === null && binding.atSlot === -1
     && binding.allowingEmpty === false;
   if (!sourceIsCollection) {
@@ -1752,9 +1793,9 @@ function planFlwor(node, shape, rawFlwor, udfHook) {
     let refused = null;
     for (const spec of node.orderby.specs) {
       const ref = pathRef(spec.key, itSlot, shape);
-      if (ref === null || ref.type === 'unknown') {
+      if (ref === null || !orderable(ref, shape.schema)) {
         refused = refusal('$orderby',
-          'ordering translates only over singular schema-typed paths');
+          'ordering translates only over singular schema-typed paths (numbers and strings that cannot hold null)');
         break;
       }
       if (spec.collation !== null || spec.collationName !== null) {
@@ -1855,12 +1896,12 @@ function planCollectionCore(document, shape, options = undefined) {
   const windows = [];
   while (root.kind === 'op' && root.name === '$subsequence') {
     const [inner, start, length] = root.args;
-    if (start?.kind !== 'literal' || typeof start.value !== 'number'
-      || (length !== undefined && (length.kind !== 'literal' || typeof length.value !== 'number'))) {
+    if (start?.kind !== 'literal' || !isWindowBound(start.value)
+      || (length !== undefined && (length.kind !== 'literal' || !isWindowBound(length.value)))) {
       // non-literal bounds: the whole document is a set residual
       return {
         analysis, plan: null, mode: 'set',
-        reasons: [refusal('$subsequence', 'window bounds must be literal numbers to push')],
+        reasons: [refusal('$subsequence', 'window bounds must be literal numbers to push (non-negative integers)')],
         rowReturn: null, udfs: [], prefilters: [], series: null,
       };
     }
@@ -1947,6 +1988,16 @@ function planCollectionCore(document, shape, options = undefined) {
       return { analysis, plan: null, mode: 'set', reasons: flwor.reasons,
         rowReturn: null, udfs: [], prefilters: flwor.prefilters, series: null };
     }
+    if (flwor.bucket !== null || flwor.bucketRefusal != null) {
+      // the phrase's items are its GROUPS; a COUNT(*) over the rows
+      // answered the row count for a `$count` of the groups
+      return {
+        analysis, plan: null, mode: 'set',
+        reasons: [refusal(aggregate.name,
+          'an aggregate over a grouped phrase folds its groups, which the engine does')],
+        rowReturn: null, udfs: [], prefilters: [], series: null,
+      };
+    }
     if (aggregate.fn === 'count') {
       if (!flwor.projectionNative) {
         return {
@@ -1964,7 +2015,8 @@ function planCollectionCore(document, shape, options = undefined) {
     const ref = pathRef(root.ret, flwor.itSlot, shape);
     const numeric = aggregate.fn === 'sum' || aggregate.fn === 'avg';
     const acceptable = ref !== null
-      && (numeric ? isNumericType(ref.type) : ref.type !== 'unknown');
+      && (numeric ? isNumericType(ref.type) : ref.type !== 'unknown')
+      && ref.type !== 'boolean' && !admitsNull(shape.schema, ref.segments);
     if (!acceptable) {
       return {
         analysis, plan: null, mode: 'set',
@@ -2069,10 +2121,30 @@ function planCollectionCore(document, shape, options = undefined) {
  * }}
  */
 export function planQuery(document, shape, options = undefined) {
-  const planned = planCollectionCore(document, shape, options);
+  const peeled = peelWrappedResult(document);
+  const planned = { ...planCollectionCore(peeled.document, shape, options), wrapped: peeled.wrapped };
   return prependRegisteredReason(planned, document, shape?.operators);
 }
 
+/**
+ * A chain's element terminal wraps its phrase in a one-item array
+ * constructor — `[<phrase>]`, the window that keeps an array-valued item
+ * one item (QUERY-PEN §6) — so the document a store receives from
+ * `toArray()`/`first()` is that constructor around the phrase. Read
+ * through it: the phrase inside plans as it would bare, and the engines
+ * answer its rows as the ONE array the constructor yields (`wrapped`),
+ * which is exactly the engine's own answer for the document. Anything
+ * else inside the brackets plans as itself and falls to the residual,
+ * where the whole document — brackets included — runs in the engine.
+ * @param {any} document
+ * @returns {{ document: any, wrapped: boolean }}
+ */
+function peelWrappedResult(document) {
+  return Array.isArray(document) && document.length === 1
+    ? { document: document[0], wrapped: true }
+    : { document, wrapped: false };
+}
+
 // ————— The entity document kind (one planner, two document kinds) —————
 
 /**
@@ -2090,7 +2162,7 @@ export function entityShape(entity, entityMapping) {
   const flavors = new Map();
   for (const column of entityMapping.columns) {
     const epoch = column.source === 'epoch(document)';
-    flavors.set(`.${column.name}`, {
+    flavors.set(canonicalOf([{ name: column.name }]), {
       column: column.name,
       flavor: epoch ? 'entity-epoch' : 'entity-column',
       storage: column.storage,
@@ -2098,8 +2170,9 @@ export function entityShape(entity, entityMapping) {
     });
   }
   for (const fk of entityMapping.foreignKeys) {
-    if (!flavors.has(`.${fk.column}`))
-      flavors.set(`.${fk.column}`, { column: fk.column, flavor: 'entity-column', storage: 'string' });
+    const fkCanonical = canonicalOf([{ name: fk.column }]);
+    if (!flavors.has(fkCanonical))
+      flavors.set(fkCanonical, { column: fk.column, flavor: 'entity-column', storage: 'string' });
   }
   return {
     collection: entity.name,
@@ -2120,8 +2193,7 @@ export function entityShape(entity, entityMapping) {
 export function entityPathRef(node, slot, shape) {
   const ref = pathRef(node, slot, shape);
   if (ref === null) return null;
-  const canonical = ref.segments
-    .map((s) => ('name' in s ? `.${s.name}` : `[${s.index}]`)).join('');
+  const canonical = canonicalOf(ref.segments);
   const flavored = shape.entityFlavors.get(canonical);
   if (flavored !== undefined) {
     return {
@@ -2157,8 +2229,7 @@ export function planEntityPredicate(node, slot, shape) {
       return { ...pred, items: pred.items.map(reflavor) };
     if (pred.p === 'not') return { ...pred, item: reflavor(pred.item) };
     if (!('ref' in pred) || pred.ref === null) return pred;
-    const canonical = pred.ref.segments
-      .map((s) => ('name' in s ? `.${s.name}` : `[${s.index}]`)).join('');
+    const canonical = canonicalOf(pred.ref.segments);
     const flavored = shape.entityFlavors.get(canonical);
     if (flavored === undefined) {
       // externals against DOC paths are not translated here (the
@@ -2228,9 +2299,9 @@ function planEntityQueryCore(document, entities, mapping, operators) {
   const windows = [];
   while (root.kind === 'op' && root.name === '$subsequence') {
     const [inner, start, length] = root.args;
-    if (start?.kind !== 'literal' || typeof start.value !== 'number'
-      || (length !== undefined && (length.kind !== 'literal' || typeof length.value !== 'number')))
-      return residual('$subsequence', 'window bounds must be literal numbers to push');
+    if (start?.kind !== 'literal' || !isWindowBound(start.value)
+      || (length !== undefined && (length.kind !== 'literal' || !isWindowBound(length.value))))
+      return residual('$subsequence', 'window bounds must be literal numbers to push (non-negative integers)');
     windows.push({ offset: start.value, limit: length === undefined ? null : length.value });
     root = inner;
     assertDecidedKind(root);
@@ -2250,7 +2321,7 @@ function planEntityQueryCore(document, entities, mapping, operators) {
   // bindings must each range over one entity's array
   const bindings = [];
   for (const binding of root.forBindings) {
-    const source = binding.expr;
+    const source = unpacked(binding.expr);
     const sourceEntity = source?.kind === 'path' && source.name === '$'
       && source.external !== true && source.segments.length === 2
       && source.segments[0].descendant !== true
@@ -2344,11 +2415,16 @@ function planEntityQueryCore(document, entities, mapping, operators) {
       const binding = byName.get(slot);
       const ref = binding === undefined
         ? null : entityPathRef(spec.key, slot, binding.shape);
+      // a boolean orders in SQL and is `JQ2005` in the engine on either
+      // flavor; a document path that admits null stores a present null
+      // (a COLUMN stores it absent, §9.3, so a nullable column pushes)
       if (ref === null || (ref.flavor === 'entity-doc' && ref.type === 'unknown')
+        || ref.type === 'boolean'
+        || (ref.flavor === 'entity-doc' && admitsNull(binding.shape.schema, ref.segments))
         || spec.collation !== null || spec.collationName !== null) {
         orderPushed = false;
         reasons.push({ construct: '$orderby',
-          reason: 'ordering translates only over typed entity paths' });
+          reason: 'ordering translates only over typed entity paths (never a boolean, never a document path that admits null)' });
         break;
       }
       terms.push({ binding, ref, desc: spec.desc === true, emptyGreatest: spec.emptyGreatest === true });
@@ -2414,7 +2490,11 @@ function planEntityQueryCore(document, entities, mapping, operators) {
  * @returns {any}
  */
 export function planEntityQuery(document, entities, mapping, operators = null) {
-  const planned = planEntityQueryCore(document, entities, mapping, operators);
+  const peeled = peelWrappedResult(document);
+  const planned = {
+    ...planEntityQueryCore(peeled.document, entities, mapping, operators),
+    wrapped: peeled.wrapped,
+  };
   return prependRegisteredReason(planned, document, operators);
 }
 
@@ -2432,13 +2512,30 @@ function collectBindingSlots(node, byName, slots) {
   }
 }
 
+/**
+ * The root expression an entity's rows are bound through — the ONE
+ * spelling of `$.<Name>[*]`: what an entity set exposes as its `root`
+ * (the hint a chain reads), and what {@link collectEntityRoots}
+ * recognises in a document. Two spellings would let a handle publish a
+ * root the planner does not read.
+ * @param {string} name - a declared entity name
+ * @returns {string}
+ */
+export function entityRoot(name) {
+  return `$.${name}[*]`;
+}
+
 /** The entity names a document's root paths reference (`$.Name[*]`). */
 export function collectEntityRoots(document, entities) {
   const found = new Set();
   const walk = (node) => {
     if (typeof node === 'string') {
-      const match = /^\$\.([A-Za-z_][A-Za-z0-9_]*)\[\*\]/.exec(node);
-      if (match !== null && entities.has(match[1])) found.add(match[1]);
+      for (const name of entities.keys()) {
+        if (node.startsWith(entityRoot(name))) {
+          found.add(name);
+          break;
+        }
+      }
       return;
     }
     if (Array.isArray(node)) {