@jarenjs/db 0.56.0 → 0.67.0

package/src/emit.js

@@ -29,8 +29,9 @@ export class UnrepresentablePath extends Error {}
 /**
  * @typedef {{ external: string } | { literal: unknown } |
  *   { derived: { kind: 'bboxAxis', external: string,
- *     axis: 'w' | 's' | 'e' | 'n' } }} ParamSlot
- *   Three kinds, closed. A DERIVED slot is the escape for a value SQL
+ *     axis: 'w' | 's' | 'e' | 'n' } } |
+ *   { typed: { seek: string, type: 'number' | 'text' } }} ParamSlot
+ *   Four kinds, closed. A DERIVED slot is the escape for a value SQL
  *   cannot bind at all: a GeoJSON region arrives as an external object,
  *   and what the statement needs is one edge of its bounding box, so
  *   the binder computes that edge from the bound value. It is the same
@@ -38,6 +39,14 @@ export class UnrepresentablePath extends Error {}
  *   cannot, bind an ordinary parameter — and it stays closed on
  *   purpose: a general expression slot would be a second query language
  *   living in the emitter.
+ *
+ *   A TYPED slot is the other direction: a scalar whose JSON type is
+ *   PROVEN before the statement binds — the database's own answer to
+ *   one of the plan's seeks, read from a column of declared type. An
+ *   external's type is only knowable at bind time, so its comparison
+ *   carries a text branch beside a number branch; a typed slot carries
+ *   one guarded comparison, the same shape a literal gets, and the
+ *   binder refuses a value of the wrong type before any SQL runs.
  */
 
 /**
@@ -77,6 +86,7 @@ function stropForm(dialect, param, valueSql, pred) {
 function slotName(slot) {
   if ('external' in slot) return slot.external;
   if ('derived' in slot) return slot.derived.external;
+  if ('typed' in slot) return slot.typed.seek;
   return 'value';
 }
 
@@ -114,14 +124,29 @@ export function emitPlan(plan, dialect, physical) {
   const docColumn = q(physical.docColumn);
   /** @type {ParamSlot[]} */
   const slots = [];
+  // the statement being emitted owns its slots: a positional dialect
+  // numbers by that statement's own text order, so a SEEK emitted
+  // beside the main statement numbers from one again
+  let sink = slots;
   const param = (slot) => {
-    slots.push(slot);
-    return dialect.parameterRef(slots.length, slotName(slot));
+    sink.push(slot);
+    return dialect.parameterRef(sink.length, slotName(slot));
   };
 
-  /** SQL for a ref's VALUE: the generated column when one exists. */
-  const valueOf = (ref) =>
-    (ref.column !== null ? q(ref.column) : dialect.jsonExtract(docColumn, pathTextOf(ref)));
+  /**
+   * SQL for a ref's VALUE: the generated column when one exists AND
+   * this dialect can compare that column's declared type against a
+   * value of `kind`. Where it cannot — an engine whose columns carry a
+   * real SQL type, asked to compare a text column with a number — the
+   * member is read out of the document instead. Same answer, unindexed,
+   * and never a type error the row's own type guard already excludes.
+   * @param {any} ref
+   * @param {'any' | 'text' | 'number' | 'boolean'} [kind]
+   */
+  const valueOf = (ref, kind = 'any') =>
+    (ref.column !== null && dialect.columnUsableFor(ref.type, kind)
+      ? q(ref.column)
+      : dialect.jsonExtract(docColumn, pathTextOf(ref), kind));
   const pathTextOf = (ref) => {
     const text = dialect.jsonPathText(ref.segments);
     if (text === null) {
@@ -132,9 +157,79 @@ export function emitPlan(plan, dialect, physical) {
   };
   /** The presence/type discriminator, always over the document column. */
   const typeOf = (ref) => dialect.jsonTypeOf(docColumn, pathTextOf(ref));
+  /** One projected member: its value beside its JSON type, under a
+   * suffixed pair of names the decoder reads back. */
+  const projectedPair = (ref, suffix) =>
+    `CASE WHEN ${typeOf(ref)} IN (${sl('object')}, ${sl('array')}) `
+    + `THEN ${dialect.jsonText(dialect.jsonExtract(docColumn, pathTextOf(ref)))} `
+    // a SCALAR leaf comes back as the value the decoder reads: the
+    // engine's own scalar where it has one, its text where every
+    // member is one JSON type and a CASE could not answer two
+    + `ELSE ${dialect.jsonExtract(docColumn, pathTextOf(ref), 'scalar')} `
+    + `END AS ${q(`v${suffix}`)}, ${typeOf(ref)} AS ${q(`t${suffix}`)}`;
 
   const sl = dialect.stringLiteral;
-  const NUMERIC = () => `(${sl('integer')}, ${sl('real')})`;
+  /** The discriminator's spellings for a JSON NUMBER, as this engine
+   * answers them: SQLite keeps `integer` and `real` apart, an engine
+   * with one JSON number type answers one name. */
+  const NUMERIC = () => `(${dialect.numericTypeNames.map(sl).join(', ')})`;
+
+  /** The comparison kind a member's DECLARED schema type implies —
+   * what a fold or an ordering over it reads the member as. An
+   * undeclared type has none, and the member is read whole. */
+  const kindOf = (ref) => {
+    switch (ref?.type) {
+      case 'integer': case 'number': return 'number';
+      case 'string': return 'text';
+      case 'boolean': return 'boolean';
+      default: return 'any';
+    }
+  };
+
+  /**
+   * One aggregate's argument, read at the kind the FOLD needs rather
+   * than at the member's own: a sum or an average is arithmetic
+   * whatever the schema says, an extreme is the member's own ordering.
+   *
+   * An engine whose columns carry a real SQL type has no fold over a
+   * member with no declared type — there is no `SUM` of a JSON value —
+   * so the whole document runs in the set residual, named, rather than
+   * reaching the database as SQL it will refuse.
+   * @param {string} fn
+   * @param {any} ref
+   * @returns {string | null}
+   */
+  const foldValue = (fn, ref) => {
+    if (ref === null || ref === undefined) return null;
+    const kind = fn === 'sum' || fn === 'avg' ? 'number' : kindOf(ref);
+    if (kind === 'any' && dialect.capabilities.untypedColumns !== true) {
+      throw new UnrepresentablePath(
+        `a ${fn} over a member the schema does not type has no fold on this engine`);
+    }
+    return valueOf(ref, kind);
+  };
+
+  /**
+   * One reference to an EXTERNAL's bound value. The slot carries the
+   * dialect's encoding with it, because the binder has no dialect: a
+   * `json` slot binds the value's JSON text, which is the one encoding
+   * a placeholder can hold whatever the member's type turns out to be.
+   * @param {string} name
+   * @returns {string}
+   */
+  const externalSlot = (name) => param(dialect.externalEncoding === 'json'
+    ? { external: name, json: true }
+    : { external: name });
+
+  /** The slot a bare column comparison binds through: a plan-time
+   * literal, or the scalar one of the plan's own seeks answers. An
+   * external is not among them — its type is unknowable at plan time,
+   * which is exactly what the guarded form exists for. */
+  const slotFor = (operand) => {
+    if ('lit' in operand) return { literal: operand.lit };
+    const seek = (plan.seeks ?? []).find((entry) => entry.name === operand.seek);
+    return { typed: { seek: seek.name, type: seek.kind } };
+  };
 
   /**
    * The guarded, total comparison forms of the truth table.
@@ -143,11 +238,11 @@ export function emitPlan(plan, dialect, physical) {
    */
   const emitCmp = (pred) => {
     const jt = typeOf(pred.ref);
-    const value = valueOf(pred.ref);
     const symbol = { eq: '=', ne: '<>', lt: '<', le: '<=', gt: '>', ge: '>=' }[pred.op];
     if ('lit' in pred.operand) {
       const lit = pred.operand.lit;
-      const kind = typeof lit === 'number' ? 'number' : 'string';
+      const kind = typeof lit === 'number' ? 'number' : 'text';
+      const value = valueOf(pred.ref, kind);
       const typeGuard = kind === 'number'
         ? `${jt} IN ${NUMERIC()}`
         : `${jt} = ${sl('text')}`;
@@ -163,15 +258,33 @@ export function emitPlan(plan, dialect, physical) {
       // NULL, and a NULL escaping through a NOT flips a row's fate
       return `(${jt} IS NOT NULL AND ${typeGuard} AND ${value} ${symbol} ${param({ literal: lit })})`;
     }
+    if ('seek' in pred.operand) {
+      // a seek's scalar comes from a column of DECLARED type, so its
+      // JSON type is known here: one guarded comparison, no branch
+      const seek = (plan.seeks ?? []).find((entry) => entry.name === pred.operand.seek);
+      const value = valueOf(pred.ref, seek.kind);
+      const typeGuard = seek.kind === 'number'
+        ? `${jt} IN ${NUMERIC()}`
+        : `${jt} = ${sl('text')}`;
+      return `(${jt} IS NOT NULL AND ${typeGuard} AND ${value} ${symbol} `
+        + `${param({ typed: { seek: seek.name, type: seek.kind } })})`;
+    }
     // external operand: its JSON type is only knowable at bind time —
-    // guard BOTH sides per branch (text with text, number with number)
+    // guard BOTH sides per branch (text with text, number with number),
+    // and read the member at the branch's own kind. Both sides go
+    // through the dialect's external forms, because on an engine whose
+    // parameters carry a type the guard does not stop the coercion: the
+    // value is bound as JSON there and compared in JSON space
     const name = pred.operand.ext;
+    const external = () => externalSlot(name);
+    const compare = (kind) => dialect.externalCompare(valueOf(pred.ref, kind), kind);
+    const against = (kind) => dialect.externalRef(external(), kind);
     const textBranch = `(${jt} IS NOT NULL AND ${jt} = ${sl('text')} AND `
-      + `${dialect.valueTypeOf(param({ external: name }))} = ${sl('text')} AND `
-      + `${value} ${pred.op === 'ne' ? '=' : symbol} ${param({ external: name })})`;
+      + `${dialect.valueTypeOf(external())} = ${sl('text')} AND `
+      + `${compare('text')} ${pred.op === 'ne' ? '=' : symbol} ${against('text')})`;
     const numberBranch = `(${jt} IS NOT NULL AND ${jt} IN ${NUMERIC()} AND `
-      + `${dialect.valueTypeOf(param({ external: name }))} IN ${NUMERIC()} AND `
-      + `${value} ${pred.op === 'ne' ? '=' : symbol} ${param({ external: name })})`;
+      + `${dialect.valueTypeOf(external())} IN ${NUMERIC()} AND `
+      + `${compare('number')} ${pred.op === 'ne' ? '=' : symbol} ${against('number')})`;
     const equalInSomeBranch = `(${textBranch} OR ${numberBranch})`;
     return pred.op === 'ne'
       ? `(${jt} IS NOT NULL AND NOT ${equalInSomeBranch})`
@@ -194,6 +307,23 @@ export function emitPlan(plan, dialect, physical) {
         return pred.value ? dialect.booleanLiteral(true) : dialect.booleanLiteral(false);
       case 'cmp':
         return emitCmp(pred);
+      case 'colCmp': {
+        const column = q(pred.column);
+        const symbol = { eq: '=', lt: '<', le: '<=', gt: '>', ge: '>=' }[pred.op];
+        return `(${column} IS NOT NULL AND ${column} ${symbol} `
+          + `${param(slotFor(pred.operand))})`;
+      }
+      case 'interval': {
+        // the declared bounds ARE the values (§8.16's precondition is a
+        // schema one), so no `json_type` guard reads the document per
+        // row; `IS NOT NULL` keeps the form total for a row with no span
+        const start = q(pred.columns.start);
+        const end = q(pred.columns.end);
+        return `(${start} IS NOT NULL AND ${end} IS NOT NULL AND `
+          + `((${start} < ${param({ literal: pred.probe.to })} `
+          + `AND ${end} > ${param({ literal: pred.probe.from })}) `
+          + `OR ${start} >= ${end}))`;
+      }
       case 'typeIs': {
         const jt = typeOf(pred.ref);
         if (pred.types.length === 0) {
@@ -209,11 +339,13 @@ export function emitPlan(plan, dialect, physical) {
       }
       case 'udf':
         // the registered deterministic predicate: reads the row's
-        // document as JSON text, answers 1 or 0 (always total)
-        return `${pred.name}(${dialect.jsonText(docColumn)})`;
+        // document as JSON text, answers 1 or 0 (always total); the
+        // second argument is the conjunct's place in the caller's
+        // document, a literal the function reports an engine error at
+        return `${pred.name}(${dialect.jsonText(docColumn)}, ${sl(pred.mount ?? '/$where')})`;
       case 'strop': {
         const jt = typeOf(pred.ref);
-        const form = stropForm(dialect, param, valueOf(pred.ref), pred);
+        const form = stropForm(dialect, param, valueOf(pred.ref, 'text'), pred);
         return `(${jt} IS NOT NULL AND ${jt} = ${sl('text')} AND ${form})`;
       }
       case 'bboxOverlap': {
@@ -297,20 +429,64 @@ export function emitPlan(plan, dialect, physical) {
     // engine scores, cuts and ranks (measured: every SQL spelling of
     // the rank loses to fetching the column and ranking in the engine,
     // and none of them runs where no function can be registered)
-    ? `${dialect.rowIdentity()} AS ${q('rid')}, ${q(plan.rank.column)} AS ${q('vec')}`
-    : plan.bucket !== null
-      ? [`${bucketSql} AS ${q(plan.bucket.as)}`,
+    // one alternative per emitted statement: the caller emits the plan
+    // once per declared width, and each carries its own column
+    ? `${dialect.rowIdentity()} AS ${q('rid')}, `
+      + `${q(plan.rank.alternatives[0].column)} AS ${q('vec')}`
+    : plan.group !== null
+      ? [...plan.group.keys.map((key, i) => projectedPair(key.ref, `k${i}`)),
+        ...plan.group.aggregates.map((entry, i) =>
+          `${dialect.groupAggregate(entry.fn, foldValue(entry.fn, entry.ref))} `
+          + `AS ${q(`a${i}`)}`)].join(', ')
+      : plan.bucket !== null
+        ? [`${bucketSql} AS ${q(plan.bucket.as)}`,
         ...plan.bucket.aggregates.map((entry) =>
-          `${dialect.groupAggregate(entry.fn,
-            entry.ref === null ? null : valueOf(entry.ref))} AS ${q(entry.as)}`)].join(', ')
+          `${dialect.groupAggregate(entry.fn, foldValue(entry.fn, entry.ref))} `
+          + `AS ${q(entry.as)}`)].join(', ')
       : plan.aggregate === null
-        ? `${dialect.jsonText(docColumn)} AS ${q('doc')}`
+        ? (plan.project === 'document'
+          ? `${dialect.jsonText(docColumn)} AS ${q('doc')}`
+          // one member path: its value and its JSON type. A scalar is
+          // the extracted SQL value itself; an object or array is
+          // rendered to JSON text, since the binary extraction of a
+          // compound is a blob. `NULL` type is an absent member (no
+          // item), 'null' a present null, 'true'/'false' a boolean the
+          // integer rendering would otherwise lose
+          : 'path' in plan.project
+            ? projectedPair(plan.project.path, '')
+            // a projection TREE: the same value/type pair per DISTINCT
+            // leaf, numbered, and nothing else — the document blob is
+            // never selected, and a leaf named twice is fetched once
+            : plan.project.leaves.map((ref, i) => projectedPair(ref, String(i))).join(', '))
         : plan.aggregate.fn === 'count'
           ? `COUNT(*) AS ${q('value')}`
-          : `${plan.aggregate.fn.toUpperCase()}(${valueOf(plan.aggregate.ref)}) AS ${q('value')}`;
+          // a REGISTERED aggregate calls the function the store
+          // registered under the plan's name; the fold is the pack's own
+          : plan.aggregate.fn === 'registered'
+            ? `${plan.aggregate.sql}(${valueOf(plan.aggregate.ref,
+              kindOf(plan.aggregate.ref))}) AS ${q('value')}`
+            : `${plan.aggregate.fn.toUpperCase()}(`
+              + `${foldValue(plan.aggregate.fn, plan.aggregate.ref)}) AS ${q('value')}`;
 
   let sql = `SELECT ${selection} FROM ${q(physical.table)}`;
   if (plan.filter !== null) sql += ` WHERE ${emitPred(plan.filter)}`;
+  if (plan.group !== null) {
+    // BY THE ALIASES the selection named, not by a second spelling of
+    // the same member. Two reasons, and the second is the load-bearing
+    // one: a key is a value/type PAIR (a JSON `1` and a JSON `"1"` are
+    // different keys and render the same text), and an engine that
+    // checks its grouping refuses a selected expression the GROUP BY
+    // does not cover — which every key's type discriminator would be.
+    sql += ` GROUP BY ${plan.group.keys
+      .map((key, i) => `${q(`vk${i}`)}, ${q(`tk${i}`)}`).join(', ')}`;
+    // the groups' order: the engine's own order of first appearance —
+    // over a collection, each group's earliest row identity — or the
+    // key ordering an `$orderby` declared
+    sql += ` ORDER BY ${plan.group.order === 'first-seen'
+      ? dialect.groupAggregate('min', dialect.rowIdentity())
+      : plan.group.order.map((term) => `${q(`vk${term.index}`)} `
+        + `${term.desc ? 'DESC' : 'ASC'}${dialect.orderNulls(term.nullsFirst)}`).join(', ')}`;
+  }
   if (plan.bucket !== null) {
     // `first-seen` is the engine's own group order (§6.5, first
     // appearance), which over a collection is the group's earliest row
@@ -321,13 +497,15 @@ export function emitPlan(plan, dialect, physical) {
       : `${alias} ${plan.bucket.order === 'desc' ? 'DESC' : 'ASC'}`;
     sql += ` GROUP BY ${alias} ORDER BY ${order}`;
   }
-  if (plan.aggregate === null && plan.rank === null && plan.bucket === null) {
+  if (plan.aggregate === null && plan.rank === null && plan.bucket === null
+    && plan.group === null) {
     const terms = (plan.order ?? []).map((term) => {
       // Jaren's default sorts an empty key least: NULLS FIRST when
       // ascending, NULLS LAST when descending — and mirrored for
       // $empty: 'greatest' (probed against the engine)
       const nullsFirst = term.emptyGreatest === term.desc;
-      return `${valueOf(term.ref)} ${term.desc ? 'DESC' : 'ASC'}${dialect.orderNulls(nullsFirst)}`;
+      return `${valueOf(term.ref, kindOf(term.ref))} `
+        + `${term.desc ? 'DESC' : 'ASC'}${dialect.orderNulls(nullsFirst)}`;
     });
     // the collection is a SEQUENCE: its order is insertion (row
     // identity) order, and the engine's sort is stable — the identity
@@ -336,10 +514,52 @@ export function emitPlan(plan, dialect, physical) {
     terms.push(dialect.rowIdentity());
     sql += ` ORDER BY ${terms.join(', ')}`;
   }
-  if (plan.window !== null && plan.aggregate === null) {
+  if (plan.window !== null && plan.aggregate === null && plan.group === null) {
     sql += ` ${dialect.limitClause(plan.window.limit, plan.window.offset)}`;
   }
-  return { sql, slots };
+  return { sql, slots, seeks: (plan.seeks ?? []).map((seek) => emitSeek(seek)) };
+
+  /**
+   * One seek statement: the extreme instant each group carries on the
+   * near side of the probe, folded to the one scalar every group's
+   * answer is beyond. Ungrouped, the inner fold IS the answer.
+   * @param {import('./algebra.js').PlanSeek} seek
+   * @returns {{ name: string, kind: 'number' | 'text',
+   *   sql: string, slots: ParamSlot[] }}
+   */
+  function emitSeek(seek) {
+    /** @type {ParamSlot[]} */
+    const own = [];
+    const outer = sink;
+    sink = own;
+    try {
+      // the seek reads the same declared columns the bound it fills does
+      const colCmp = (column, op, lit) =>
+        ({ p: 'colCmp', op, column, operand: { lit } });
+      /** @type {import('./algebra.js').PlanPredicate} */
+      let filter = colCmp(seek.ref.column, seek.bound.op, seek.bound.lit);
+      if (seek.group !== null && seek.keys !== null && seek.keys.length > 0) {
+        filter = { p: 'and', items: [filter, seek.keys.length === 1
+          ? colCmp(seek.group.column, 'eq', seek.keys[0])
+          : { p: 'or', items: seek.keys.map((key) =>
+            colCmp(seek.group.column, 'eq', key)) }] };
+      }
+      const inner = `${seek.inner.toUpperCase()}(${valueOf(seek.ref, seek.kind)})`;
+      const where = ` FROM ${q(physical.table)} WHERE ${emitPred(filter)}`;
+      const text = seek.group === null
+        ? `SELECT ${inner} AS ${q('anchor')}${where}`
+        : `SELECT ${seek.outer.toUpperCase()}(${q('a')}) AS ${q('anchor')} FROM `
+          + `(SELECT ${inner} AS ${q('a')}${where} `
+          + `GROUP BY ${valueOf(seek.group, kindOf(seek.group))})`;
+      // a seek that finds nothing binds its own probe: it proved there
+      // is no row on that side, so the bound excludes only what is absent
+      return { name: seek.name, kind: seek.kind, fallback: seek.bound.lit,
+        sql: text, slots: own };
+    }
+    finally {
+      sink = outer;
+    }
+  }
 }
 
 // ————— The entity document kind (one emitter layer, two kinds) —————
@@ -355,7 +575,11 @@ export function emitPlan(plan, dialect, physical) {
 export function createEntityPredicateEmitters(dialect, param) {
   const q = dialect.quoteIdentifier;
   const sl = dialect.stringLiteral;
-  const NUMERIC = () => `(${sl('integer')}, ${sl('real')})`;
+  const NUMERIC = () => `(${dialect.numericTypeNames.map(sl).join(', ')})`;
+  const externalSlot = (name) => param(dialect.externalEncoding === 'json'
+    ? { external: name, json: true }
+    : { external: name });
+
   const pathTextOf = (ref) => {
     const text = dialect.jsonPathText(ref.segments);
     if (text === null)
@@ -363,9 +587,14 @@ export function createEntityPredicateEmitters(dialect, param) {
     return text;
   };
 
+  /** The member at a ref, read as the SQL a comparison of that KIND
+   * needs. On a dynamically typed engine every kind is the same read;
+   * on one whose columns carry a real type they are four. */
+  const memberAt = (docSql, ref, kind) =>
+    dialect.jsonExtract(docSql, pathTextOf(ref), kind);
+
   const emitDocPred = (docSql, pred) => {
     const jt = dialect.jsonTypeOf(docSql, pathTextOf(pred.ref));
-    const value = dialect.jsonExtract(docSql, pathTextOf(pred.ref));
     if (pred.p === 'typeIs') {
       if (pred.types.length === 0)
         return pred.positive ? `${jt} IS NOT NULL` : `${jt} IS NULL`;
@@ -376,12 +605,13 @@ export function createEntityPredicateEmitters(dialect, param) {
         : `(${jt} IS NOT NULL AND ${jt} NOT IN (${list}))`;
     }
     if (pred.p === 'strop') {
-      const form = stropForm(dialect, param, value, pred);
+      const form = stropForm(dialect, param, memberAt(docSql, pred.ref, 'text'), pred);
       return `(${jt} IS NOT NULL AND ${jt} = ${sl('text')} AND ${form})`;
     }
     const lit = pred.operand.lit;
     const symbol = { eq: '=', ne: '<>', lt: '<', le: '<=', gt: '>', ge: '>=' }[pred.op];
-    const kind = typeof lit === 'number' ? 'number' : 'string';
+    const kind = typeof lit === 'number' ? 'number' : 'text';
+    const value = memberAt(docSql, pred.ref, kind);
     if (pred.op === 'ne') {
       const notType = kind === 'number'
         ? `${jt} NOT IN ${NUMERIC()}` : `${jt} <> ${sl('text')}`;
@@ -410,10 +640,13 @@ export function createEntityPredicateEmitters(dialect, param) {
     }
     const symbol = { eq: '=', ne: '<>', lt: '<', le: '<=', gt: '>', ge: '>=' }[pred.op];
     if ('ext' in pred.operand) {
-      const guard = pred.ref.storage === 'string'
-        ? `${dialect.valueTypeOf(param({ external: pred.operand.ext }))} = ${sl('text')}`
-        : `${dialect.valueTypeOf(param({ external: pred.operand.ext }))} IN ${NUMERIC()}`;
-      return `(${column} IS NOT NULL AND ${guard} AND ${column} ${pred.op === 'ne' ? '<>' : symbol} ${param({ external: pred.operand.ext })})`;
+      const kind = pred.ref.storage === 'string' ? 'text' : 'number';
+      const guard = kind === 'text'
+        ? `${dialect.valueTypeOf(externalSlot(pred.operand.ext))} = ${sl('text')}`
+        : `${dialect.valueTypeOf(externalSlot(pred.operand.ext))} IN ${NUMERIC()}`;
+      return `(${column} IS NOT NULL AND ${guard} AND `
+        + `${dialect.externalCompare(column, kind)} ${pred.op === 'ne' ? '<>' : symbol} `
+        + `${dialect.externalRef(externalSlot(pred.operand.ext), kind)})`;
     }
     const lit = pred.operand.lit;
     const litKind = typeof lit === 'number' ? 'number' : typeof lit === 'string' ? 'string' : 'other';
@@ -432,7 +665,9 @@ export function createEntityPredicateEmitters(dialect, param) {
   // stored values carry
   const emitEpochPred = (aliasSql, docSql, pred) => {
     const column = `${aliasSql}.${q(pred.ref.column)}`;
-    const value = dialect.jsonExtract(docSql, pathTextOf(pred.ref));
+    // the stored TEXT decides: an instant's codepoint comparison is
+    // exactly the engine's, whatever precision the value carries
+    const value = memberAt(docSql, pred.ref, 'text');
     const symbol = { eq: '=', lt: '<', le: '<=', gt: '>', ge: '>=' }[pred.op];
     const range = pred.op === 'gt' || pred.op === 'ge'
       ? `${column} >= ${param({ literal: pred.epoch - 1000 })}`
@@ -483,6 +718,7 @@ export function createEntityPredicateEmitters(dialect, param) {
  */
 export function emitEntityPlan(plan, dialect, physicalOf) {
   const q = dialect.quoteIdentifier;
+  const sl = dialect.stringLiteral;
   /** @type {ParamSlot[]} */
   const slots = [];
   const param = (slot) => {
@@ -503,25 +739,80 @@ export function emitEntityPlan(plan, dialect, physicalOf) {
     return text;
   };
 
+  const entityOf = new Map(plan.bindings.map((binding) => [binding.name, binding.entity]));
   const emitters = createEntityPredicateEmitters(dialect, param);
   const emitPred = (bindingName, pred) =>
     emitters.emitPred(aliasOf(bindingName), docOf(bindingName), pred);
 
+  /**
+   * One projected member of a binding: its value beside its JSON type,
+   * under a suffixed pair of names the decoder reads back.
+   *
+   * Which SOURCE the pair reads is the entity mapping's rule (§9.3),
+   * not a choice: a mapped scalar lives in its COLUMN and is absent
+   * from the document, so reading the document for it would answer
+   * nothing; an epoch column keeps its string IN the document, because
+   * the integer is derived; everything else is document only. The type
+   * of a column value is the column's declared storage — SQL has no
+   * `json_type` for it — with `NULL` meaning the member is absent,
+   * which is exactly what the merge reads back.
+   */
+  const projectedPair = (leaf, suffix) => {
+    const names = `${q(`v${suffix}`)}`;
+    const typeName = `${q(`t${suffix}`)}`;
+    if (leaf.ref.flavor === 'entity-column') {
+      const column = `${aliasOf(leaf.binding)}.${q(leaf.ref.column)}`;
+      const type = leaf.ref.storage === 'boolean'
+        ? `CASE WHEN ${column} IS NULL THEN NULL WHEN ${column} = 0 `
+          + `THEN ${sl('false')} ELSE ${sl('true')} END`
+        : `CASE WHEN ${column} IS NULL THEN NULL ELSE ${sl(
+          leaf.ref.storage === 'string' ? 'text'
+            : leaf.ref.storage === 'integer'
+              ? dialect.numericTypeNames[0]
+              : dialect.numericTypeNames[dialect.numericTypeNames.length - 1])} END`;
+      return `${column} AS ${names}, ${type} AS ${typeName}`;
+    }
+    const docSql = docOf(leaf.binding);
+    const text = pathTextOf(leaf.ref);
+    const type = dialect.jsonTypeOf(docSql, text);
+    return `CASE WHEN ${type} IN (${sl('object')}, ${sl('array')}) `
+      + `THEN ${dialect.jsonText(dialect.jsonExtract(docSql, text))} `
+      + `ELSE ${dialect.jsonExtract(docSql, text, 'scalar')} END AS ${names}, `
+      + `${type} AS ${typeName}`;
+  };
+
   const ret = plan.ret;
   // every returned column plus the document rendered to text; the
-  // caller merges them back into the entity shape
+  // caller merges them back into the entity shape — or, for a projected
+  // shape, one value/type pair per DISTINCT leaf and no document at all
   const selection = plan.aggregate === 'count'
     ? `COUNT(*) AS ${q('value')}`
-    : `${aliasOf(ret)}.*, ${dialect.jsonText(docOf(ret))} AS ${q('__doc')}`;
+    : plan.project != null
+      // `p`-prefixed, because a bare `t0` would collide with this
+      // plan's own binding aliases
+      ? plan.project.leaves.map((leaf, i) => projectedPair(leaf, `p${i}`)).join(', ')
+      // a join-table root IS its two key columns: it has no document
+      // column, so the merge is handed an empty one
+      : physicalOf(entityOf.get(ret)).document === false
+        ? `${aliasOf(ret)}.*, ${sl('{}')} AS ${q('__doc')}`
+        : `${aliasOf(ret)}.*, ${dialect.jsonText(docOf(ret))} AS ${q('__doc')}`;
+
+  const tableOf = (name) =>
+    `${q(physicalOf(entityOf.get(name)).table)} AS ${aliasOf(name)}`;
+  const JOIN_OPS = { eq: '=', ne: '<>', lt: '<', le: '<=', gt: '>', ge: '>=' };
+  const onSql = (edge) =>
+    `${aliasOf(edge.left.binding)}.${q(edge.left.column)}`
+    + ` ${JOIN_OPS[edge.op ?? 'eq']} ${aliasOf(edge.right.binding)}.${q(edge.right.column)}`;
 
   let sql = `SELECT ${selection} FROM `;
-  sql += plan.bindings
-    .map((binding) => `${q(physicalOf(binding.entity).table)} AS ${aliasOf(binding.name)}`)
-    .join(' JOIN ');
-  if (plan.joinOn !== null) {
-    sql += ` ON ${aliasOf(plan.joinOn.left.binding)}.${q(plan.joinOn.left.column)}`
-      + ` = ${aliasOf(plan.joinOn.right.binding)}.${q(plan.joinOn.right.column)}`;
-  }
+  // the JOIN order the planner settled: the first binding, then each
+  // one an edge attaches to what is already joined. A binding nothing
+  // attached never reaches here — that graph is the residual
+  sql += plan.joins.length === 0
+    ? tableOf(plan.bindings[0].name)
+    : plan.joins.map((join, i) => (i === 0
+      ? tableOf(join.binding)
+      : `${tableOf(join.binding)} ON ${join.on.map(onSql).join(' AND ')}`)).join(' JOIN ');
   const filterSql = plan.filters
     .filter((entry) => entry.filter !== null)
     .map((entry) => emitPred(entry.binding, entry.filter));
@@ -535,7 +826,7 @@ export function emitEntityPlan(plan, dialect, physicalOf) {
       // integer column sort differently
       const value = term.ref.flavor === 'entity-column'
         ? `${aliasOf(term.binding)}.${q(term.ref.column)}`
-        : dialect.jsonExtract(docOf(term.binding), pathTextOf(term.ref));
+        : dialect.jsonExtract(docOf(term.binding), pathTextOf(term.ref), 'text');
       const nullsFirst = term.emptyGreatest === term.desc;
       return `${value} ${term.desc ? 'DESC' : 'ASC'}${dialect.orderNulls(nullsFirst)}`;
     });

package/src/entity.js

@@ -18,8 +18,9 @@ import { compileJsonQuery } from '@jarenjs/json/query';
 import {
   getEpochOfDateTimeRFC3339, getEpochOfDateOnlyRFC3339,
 } from '@jarenjs/core/dates/rfc3339';
+import { resolveRuntime } from '@jarenjs/core/runtime';
 
-import { DbRuntimeError, isDuplicateKeyError } from './errors.js';
+import { DbRuntimeError, wrapDriverError } from './errors.js';
 import { chain, attempt } from './driver.js';
 
 /**
@@ -28,9 +29,13 @@ import { chain, attempt } from './driver.js';
  * @param {any} entity - the normalized entity (model.js)
  * @param {any} entityMapping - `explainMapping(...).entities[name]`
  * @param {((doc: any) => any) | null} validate
+ * @param {Partial<import('@jarenjs/core/runtime').Runtime>} [runtime] - the
+ *   host's runtime record: the clock a `default: 'now'` stamps and the
+ *   identifier a `default: 'uuid'` allocates; the platform's own when absent
  * @returns {any}
  */
-export function entityCore(connection, entity, entityMapping, validate) {
+export function entityCore(connection, entity, entityMapping, validate, runtime = undefined) {
+  const host = resolveRuntime(runtime);
   const dialect = connection.dialect;
   const q = dialect.quoteIdentifier;
   const table = entityMapping.table;
@@ -164,14 +169,14 @@ export function entityCore(connection, entity, entityMapping, validate) {
       // a `date` property takes the calendar date; a date-time stamp on
       // it was invalid under its own format and refused by an epoch column
       const stamp = property.format === 'date'
-        ? () => new Date().toISOString().slice(0, 10)
-        : () => new Date().toISOString();
+        ? () => new Date(host.now()).toISOString().slice(0, 10)
+        : () => new Date(host.now()).toISOString();
       defaulters.push({ name: property.name, fill: stamp });
       if (declared === 'updated') updateStamps.push({ name: property.name, fill: stamp });
       continue;
     }
     if (declared === 'uuid') {
-      defaulters.push({ name: property.name, fill: () => crypto.randomUUID() });
+      defaulters.push({ name: property.name, fill: () => host.uuid() });
       continue;
     }
     if (declared === 'auto') continue; // the database allocates
@@ -243,7 +248,7 @@ export function entityCore(connection, entity, entityMapping, validate) {
   const prepared = (name, sql) => {
     let statement = statements.get(name);
     if (statement === undefined) {
-      statement = connection.prepare(sql);
+      statement = connection.prepare(sql, { readOnly: name === 'get' });
       statements.set(name, statement);
     }
     return statement;
@@ -288,20 +293,11 @@ export function entityCore(connection, entity, entityMapping, validate) {
       { docPath, collection: entity.name });
   };
 
-  const wrapWrite = (error, key) => {
-    const code = /** @type {any} */ (error)?.code;
-    if (typeof code === 'string' && code.startsWith('JD')) return error;
-    if (keys.length === 1 && isDuplicateKeyError(error, table, keys[0])) {
-      return new DbRuntimeError('JD2001',
-        `a '${entity.name}' already exists under key ${JSON.stringify(key)}`,
-        { docPath, collection: entity.name, key, cause: error });
-    }
-    return new DbRuntimeError('JD2005',
-      `the database rejected the operation: ${/** @type {any} */ (error)?.message ?? String(error)}`,
-      key === undefined
-        ? { docPath, collection: entity.name, cause: error }
-        : { docPath, collection: entity.name, key, cause: error });
-  };
+  const wrapWrite = (error, key) => wrapDriverError(error, {
+    docPath, collection: entity.name, ...(key === undefined ? undefined : { key }),
+    ...(keys.length === 1 ? { unique: { table, column: keys[0] } } : undefined),
+    duplicateReason: `a '${entity.name}' already exists under key ${JSON.stringify(key)}`,
+  });
 
   const columnByName = new Map(scalarColumns.map((column) => [column.name, column]));
   /** Encode ONE column assignment the way {@link split} would. */
@@ -360,8 +356,10 @@ export function entityCore(connection, entity, entityMapping, validate) {
     get(key) {
       const parts = normalizeKeyArg(key);
       const sql = `SELECT ${selectColumns} FROM ${q(table)} WHERE ${keyWhere(0)}`;
-      return chain(prepared('get', sql), (statement) =>
-        chain(statement.get(parts), (row) => (row === undefined ? undefined : merge(row))));
+      // classified like every read of the query engines, never raw
+      return attempt(() => chain(prepared('get', sql), (statement) =>
+        chain(statement.get(parts), (row) => (row === undefined ? undefined : merge(row)))),
+      (error) => wrapDriverError(error, { docPath, collection: entity.name, key }));
     },
     update(key, changes) {
       const parts = normalizeKeyArg(key);