@jarenjs/db 0.75.0 → 0.83.3

package/src/physical.js

@@ -0,0 +1,147 @@
+//@ts-check
+/** Explicit column layouts and lossless JSON-facing column codecs. */
+import { getEpochOfDateTimeRFC3339, getEpochOfDateOnlyRFC3339 } from '@jarenjs/core/dates/rfc3339';
+import { DbCompileError, DbRuntimeError } from './errors.js';
+import { chain } from './driver.js';
+import { canonicalizeJson } from '@jarenjs/json/canonical';
+
+const compiledCodecs = new WeakMap();
+const CODECS = new Set(['text', 'integer', 'number', 'boolean', 'json', 'date', 'datetime', 'epoch-ms', 'bigint', 'decimal', 'blob-hex']);
+const STORAGE = { text: 'string', integer: 'integer', number: 'number', boolean: 'boolean',
+  json: 'string', date: 'string', datetime: 'string', 'epoch-ms': 'integer', bigint: 'integer', decimal: 'string', 'blob-hex': 'string' };
+const identifier = (v) => typeof v === 'string' && v.length > 0 && !v.includes('\0');
+
+/** Normalize a declared layout; implicit conversions are never adoption policy.
+ * @param {any} physical @param {Map<string, any>} properties @param {string[]} keys
+ * @param {string} path @returns {any} */
+export function normalizePhysical(physical, properties, keys, path) {
+  if (physical === undefined) return null;
+  const fail = (reason) => { throw new DbCompileError('JD0005', reason, `${path}/physical`); };
+  if (!physical || typeof physical !== 'object' || Array.isArray(physical)) fail('physical must be an object');
+  for (const key of Object.keys(physical))
+    if (!['table', 'kind', 'keys', 'columns'].includes(key)) fail(`unknown physical member '${key}'`);
+  if (!identifier(physical.table)) fail('physical.table must be a nonempty SQL identifier');
+  if (physical.kind !== undefined && !['table', 'view'].includes(physical.kind)) fail('physical.kind is table or view');
+  if (!physical.columns || typeof physical.columns !== 'object' || Array.isArray(physical.columns)) fail('physical.columns is required');
+  const ordered = physical.keys ?? keys;
+  if (!Array.isArray(ordered) || ordered.length !== keys.length || new Set(ordered).size !== keys.length
+    || ordered.some((key) => !keys.includes(key))) fail('physical.keys must order every declared key exactly once');
+  const used = new Set();
+  const columns = [];
+  for (const [name, property] of properties) {
+    if (property.relation) continue;
+    const c = physical.columns[name];
+    if (!c || typeof c !== 'object' || Array.isArray(c) || !CODECS.has(c.codec)) fail(`'${name}' needs an explicit supported column codec`);
+    for (const key of Object.keys(c))
+      if (!['name', 'codec', 'null', 'default', 'generated'].includes(key)) fail(`unknown column member '${key}'`);
+    if (!identifier(c.name) || used.has(c.name.toLowerCase())) fail(`'${name}' needs a distinct physical column name`);
+    if (!['null', 'absent', 'reject'].includes(c.null)) fail(`'${name}' must declare SQL NULL as null, absent or reject`);
+    if (c.default !== undefined && c.default !== 'database') fail('column default ownership is database');
+    if (c.generated !== undefined && typeof c.generated !== 'boolean') fail('generated must be boolean');
+    if (property.key && (!['text', 'integer', 'bigint'].includes(c.codec) || c.null !== 'reject')) fail('keys require non-null text, integer or bigint codecs');
+    if (property.column !== undefined) fail('physical codecs replace hybrid column overrides');
+    if (c.default === 'database' && property.default !== undefined && property.default !== 'auto') fail('a default has exactly one owner');
+    used.add(c.name.toLowerCase());
+    columns.push({ name, physical: c.name, codec: c.codec, null: c.null, databaseDefault: c.default === 'database',
+      generated: c.generated === true, storage: STORAGE[c.codec], source: 'column', key: property.key });
+  }
+  for (const name of Object.keys(physical.columns))
+    if (!properties.has(name) || properties.get(name).relation) fail(`column '${name}' is not a stored property`);
+  return { table: physical.table, kind: physical.kind ?? 'table', keys: [...ordered], columns };
+}
+
+/** Compile one codec once, with a JSON-safe public value and a bound SQL value.
+ * @param {any} column @returns {{ encode: Function, decode: Function, normalize: Function }} */
+export function columnCodec(column) {
+  if (compiledCodecs.has(column)) return compiledCodecs.get(column);
+  const fail = () => { throw new DbRuntimeError('JD2003', `column '${column.name}' refuses a lossy or invalid ${column.codec} value`); };
+  const date = (v, only) => typeof v === 'string' && Number.isFinite(only
+    ? getEpochOfDateOnlyRFC3339(v) : getEpochOfDateTimeRFC3339(v));
+  const convert = (v, reading) => {
+    if (v === undefined || v === null) {
+      if (!reading && v === null && column.codec === 'json') return 'null';
+      if (column.null === 'reject') return fail();
+      return reading ? (column.null === 'absent' ? undefined : null) : null;
+    }
+    switch (column.codec) {
+      case 'text': if (typeof v === 'string') return v; break;
+      case 'integer': if (typeof v === 'number' && Number.isSafeInteger(v)) return v; break;
+      case 'number': if (typeof v === 'number' && Number.isFinite(v) && (!Number.isInteger(v) || Number.isSafeInteger(v))) return v; break;
+      case 'boolean':
+        if (reading && (v === 0 || v === 1 || typeof v === 'boolean')) return v === 1 || v === true;
+        if (!reading && typeof v === 'boolean') return v ? 1 : 0;
+        break;
+      case 'bigint': if (typeof v === 'string' && /^(?:0|-?[1-9][0-9]*)$/.test(v)
+        && BigInt(v) >= -9223372036854775808n && BigInt(v) <= 9223372036854775807n) return v; break;
+      case 'decimal': if (typeof v === 'string' && /^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$/.test(v)) return v; break;
+      case 'date': if (date(v, true)) return v; break;
+      case 'datetime': if (date(v, false)) return v; break;
+      case 'epoch-ms':
+        if (reading && typeof v === 'number' && Number.isSafeInteger(v) && Number.isFinite(new Date(v).getTime())) return new Date(v).toISOString();
+        if (!reading && date(v, false) && new Date(v).toISOString() === v) return getEpochOfDateTimeRFC3339(v);
+        break;
+      case 'blob-hex':
+        if (typeof v === 'string' && /^(?:[0-9a-fA-F]{2})*$/.test(v))
+          return reading ? v.toLowerCase() : Uint8Array.from(v.match(/../g) ?? [], (b) => parseInt(b, 16));
+        break;
+      case 'json':
+        try {
+          if (reading) return JSON.parse(v);
+          canonicalizeJson(v);
+          const text = JSON.stringify(v);
+          if (text !== undefined && JSON.stringify(JSON.parse(text)) === text) return text;
+        }
+        catch { return fail(); }
+        break;
+    }
+    return fail();
+  };
+  const codec = { encode: (v) => convert(v, false), decode: (v) => convert(v, true), normalize: (v) => {
+    const encoded = convert(v, false);
+    return column.codec === 'blob-hex' && encoded !== null ? v.toLowerCase() : convert(encoded, true);
+  } };
+  compiledCodecs.set(column, codec);
+  return codec;
+}
+
+/** SQL selection keeps unsafe integers and byte handles out of application state.
+ * @param {any} column @param {any} dialect @param {string} [prefix] @returns {string} */
+export function physicalRead(column, dialect, prefix = '') {
+  const sql = `${prefix}${dialect.quoteIdentifier(column.physical ?? column.name)}`;
+  return dialect.physicalRead(column.codec, sql);
+}
+
+/** Verify an existing mapped object without executing DDL. Unmapped columns and
+ * all application-owned programs remain physical facts, never inferred drops.
+ * @param {any} connection @param {any} mapping @param {any} schema @returns {any} */
+export function verifyPhysical(connection, mapping, schema) {
+  const fail = (why) => { throw new DbCompileError('JD0002', `physical '${mapping.table}': ${why}`); };
+  if (connection.dialect.name !== 'sqlite') fail('column adoption is qualified only for SQLite');
+  const object = schema.objects.find((o) => o.name === mapping.table && o.type === mapping.kind);
+  if (!object) fail(`declared ${mapping.kind} does not exist`);
+  for (const trigger of mapping.triggers ?? []) {
+    const actual = schema.objects.find((o) => o.type === 'trigger' && o.name === trigger.name);
+    if (!actual || actual.sql?.trim().replace(/;$/, '') !== trigger.sql.trim().replace(/;$/, '')) fail(`invariant trigger '${trigger.name}' is missing or changed; apply an explicit migration`);
+  }
+  const read = mapping.kind === 'view'
+    ? chain(connection.prepare(connection.dialect.introspect.columns(mapping.table)), (s) =>
+      chain(s.all([]), (columns) => ({ columns: columns.map((c) => ({ ...c, generated: !!c.hidden })), primaryKey: [] })))
+    : schema.tables.find((t) => t.name === mapping.table);
+  return chain(read, (table) => {
+    if (mapping.kind !== 'view' && JSON.stringify(table.primaryKey) !== JSON.stringify(mapping.keys.map((k) => mapping.columns.find((c) => c.name === k).physical))) fail('ordered primary key disagrees');
+    for (const column of mapping.columns) {
+      const actual = table.columns.find((c) => c.name === column.physical);
+      if (!actual) fail(`column '${column.physical}' does not exist`);
+      const type = actual.type.toUpperCase();
+      if (!connection.dialect.physicalTypeMatches(column.codec, type)) fail(`'${column.physical}' type ${type} cannot guarantee codec ${column.codec}`);
+      if (mapping.kind !== 'view' && actual.generated !== column.generated) fail(`'${column.physical}' generated ownership disagrees`);
+    }
+    return null;
+  });
+}
+
+/** Select mapped columns with their physical aliases for the shared row merger.
+ * @param {any} mapping @param {any} dialect @param {string} [prefix] @returns {string} */
+export function physicalSelection(mapping, dialect, prefix = '') {
+  return mapping.columns.map((c) => `${physicalRead(c, dialect, prefix)} AS ${dialect.quoteIdentifier(c.physical ?? c.name)}`).join(', ');
+}

package/src/plan.js

@@ -95,6 +95,7 @@ const KIND_REASONS = {
 
 /** Why one PREDICATE stayed in the engine. */
 const PREDICATE_REASONS = {
+  physicalCodec: 'this codec or NULL policy requires decoded-row evaluation',
   notPredicate: 'not a predicate the planner translates',
   negatedPrefilter: 'a negated predicate cannot ride an implied pre-filter '
     + '(negating a superset drops rows)',
@@ -187,7 +188,8 @@ const ENTITY_REASONS = {
     + 'a binding nothing connects is a cartesian product, which is engine work',
   conjunctBinding: 'a conjunct must belong to one binding (or be the single join equality)',
   external: 'externals compare only against entity columns in this version',
-  projection: 'entity queries return one bare binding natively; projections run in the engine',
+  projection: 'this entity return or grouping needs decoded-row evaluation',
+  groupOrder: 'first-seen grouping over a compound physical key requires tuple ordering',
   order: 'ordering translates only over typed entity paths (never a boolean, never a document '
     + 'path that admits null)',
 };
@@ -2093,12 +2095,12 @@ function planSeriesOperator(root, shape) {
  * @param {any} shape
  * @returns {any | null}
  */
-function planGeneralGrouping(node, itSlot, shape) {
+function planGeneralGrouping(node, itSlot, shape, resolve = pathRef) {
   const keys = [];
   /** @type {Map<number, number>} */
   const keySlot = new Map();
   for (const key of node.groupby.keys) {
-    const ref = pathRef(key.expr, itSlot, shape);
+    const ref = resolve(key.expr, itSlot, shape);
     if (ref === null || ref.type === 'unknown')
       return null;
     keySlot.set(key.slot, keys.length);
@@ -2113,7 +2115,7 @@ function planGeneralGrouping(node, itSlot, shape) {
     if (child.kind === 'var' && child.external !== true && keySlot.has(child.slot))
       return { p: 'key', index: keySlot.get(child.slot) };
     if (child.kind === 'op') {
-      const entry = groupAggregate(child, itSlot, shape);
+      const entry = groupAggregate(child, itSlot, shape, resolve);
       if (entry === null) return null;
       // one aggregate per distinct (function, path): two members that
       // ask the same question are one SQL aggregate
@@ -2167,14 +2169,36 @@ function planGeneralGrouping(node, itSlot, shape) {
  * @param {any} shape
  * @returns {{ as: string, fn: string, ref: any, empty: string } | null}
  */
-function groupAggregate(node, itSlot, shape) {
+function groupAggregate(node, itSlot, shape, resolve = pathRef) {
+  // SQL's nullable sum is authored explicitly: test for any non-null
+  // values, sum exactly that sequence, otherwise return a literal null.
+  if (node.name === '$if' && node.args[0]?.name === '$exists'
+    && node.args[1]?.name === '$sum' && node.args[2]?.kind === 'literal' && node.args[2].value === null) {
+    const filtered = (phrase) => {
+      if (phrase?.kind !== 'flwor' || phrase.forBindings.length !== 1 || phrase.letBindings.length
+        || phrase.groupby !== null || phrase.orderby !== null || phrase.fold !== null
+        || phrase.count !== null || phrase.asChecks !== null) return null;
+      const binding = phrase.forBindings[0];
+      if (!isItVar(unpacked(binding.expr), itSlot) || binding.window !== null || binding.atSlot !== -1 || binding.allowingEmpty) return null;
+      const ref = resolve(phrase.ret, binding.slot, shape);
+      const where = phrase.where;
+      if (ref === null || !isNumericType(ref.type) || where?.name !== '$ne') return null;
+      const other = resolve(where.args[0], binding.slot, shape);
+      return other !== null && canonicalOf(other.segments) === canonicalOf(ref.segments)
+        && where.args[1]?.kind === 'literal' && where.args[1].value === null ? ref : null;
+    };
+    const test = filtered(node.args[0].args[0]);
+    const sum = filtered(node.args[1].args[0]);
+    return test !== null && sum !== null && canonicalOf(test.segments) === canonicalOf(sum.segments)
+      ? { fn: 'sum', ref: sum, empty: 'null' } : null;
+  }
   if (node.name === '$count') {
     return isItVar(node.args[0], itSlot)
       ? { fn: 'rows', ref: null, empty: 'zero' } : null;
   }
   const fn = AGGREGATES.get(node.name);
   if (fn === undefined || fn === 'count') return null;
-  const ref = pathRef(node.args[0], itSlot, shape);
+  const ref = resolve(node.args[0], itSlot, shape);
   const numeric = fn === 'sum' || fn === 'avg';
   const acceptable = ref !== null
     && (numeric ? isNumericType(ref.type) : ref.type !== 'unknown')
@@ -2958,10 +2982,14 @@ export function entityShape(entity, entityMapping) {
   for (const column of entityMapping.columns) {
     const epoch = column.source === 'epoch(document)';
     flavors.set(canonicalOf([{ name: column.name }]), {
-      column: column.name,
+      column: column.physical ?? column.name,
       flavor: epoch ? 'entity-epoch' : 'entity-column',
       storage: column.storage,
+      codec: column.codec,
+      codecColumn: column.codec === undefined ? undefined : column,
+      nullPolicy: column.null,
       format: epoch ? entity.properties.get(column.name)?.format : undefined,
+      unsafe: column.codec !== undefined && !['text', 'integer', 'number', 'boolean', 'date', 'datetime'].includes(column.codec),
     });
   }
   for (const fk of entityMapping.foreignKeys) {
@@ -2974,6 +3002,7 @@ export function entityShape(entity, entityMapping) {
     schema: entity.schema,
     columnByCanonical: new Map(),
     entityFlavors: flavors,
+    columnOnly: entityMapping.document === false,
   };
 }
 
@@ -2990,6 +3019,7 @@ export function entityPathRef(node, slot, shape) {
   if (ref === null) return null;
   const canonical = canonicalOf(ref.segments);
   const flavored = shape.entityFlavors.get(canonical);
+  if (flavored?.unsafe || (shape.columnOnly && flavored === undefined)) return null;
   if (flavored !== undefined) {
     return {
       ...ref,
@@ -2997,6 +3027,9 @@ export function entityPathRef(node, slot, shape) {
       flavor: flavored.flavor,
       storage: flavored.storage,
       format: flavored.format,
+      nullPolicy: flavored.nullPolicy,
+      codec: flavored.codec,
+      codecColumn: flavored.codecColumn,
     };
   }
   // a nested path rides the JSONB document with the phase-A guards;
@@ -3015,13 +3048,48 @@ export function entityPathRef(node, slot, shape) {
  * @param {Map<number, any>} byName - binding slot → binding
  * @returns {{ tree: any, leaves: { binding: string, ref: any }[] } | null}
  */
-function entityProjectionTree(node, byName) {
+function entityProjectionTree(node, byName, entities, mapping) {
   const leaves = [];
   /** @type {Map<string, number>} */
   const byCanonical = new Map();
   const build = (child) => {
     assertDecidedKind(child);
     if (child.kind === 'literal') return { p: 'lit', value: child.value };
+    if (child.kind === 'op' && child.name === '$count') {
+      const inner = child.args[0];
+      if (inner?.kind !== 'flwor' || inner.forBindings.length !== 1 || inner.groupby !== null
+        || inner.fold !== null || inner.orderby !== null || inner.letBindings.length
+        || inner.asChecks !== null || inner.count !== null) return null;
+      const binding = inner.forBindings[0];
+      const entity = bindingEntity(binding, entities);
+      if (entity === null || binding.window !== null || binding.atSlot !== -1 || binding.allowingEmpty
+        || inner.ret.kind !== 'var' || inner.ret.slot !== binding.slot) return null;
+      const shape = entityShape(entities.get(entity), mapping.entities[entity]);
+      const innerBinding = { name: binding.name, slot: binding.slot, entity, shape };
+      const scope = new Map([...byName, [binding.slot, innerBinding]]);
+      const conjuncts = inner.where?.kind === 'op' && inner.where.name === '$and' ? inner.where.args : [inner.where];
+      const edges = [];
+      let filter = null;
+      for (const conjunct of conjuncts) {
+        if (conjunct === null) continue;
+        const cross = conjunct.kind === 'op' && conjunct.name === '$eq'
+          ? crossBindingComparison(conjunct, scope) : null;
+        if (cross !== null && (cross.left.binding === innerBinding || cross.right.binding === innerBinding)) {
+          edges.push({ left: { binding: cross.left.binding.name, ref: cross.left.ref },
+            right: { binding: cross.right.binding.name, ref: cross.right.ref } });
+          continue;
+        }
+        const slots = new Set(); collectBindingSlots(conjunct, scope, slots);
+        if (slots.size !== 1 || !slots.has(binding.slot)) return null;
+        const planned = planEntityPredicate(conjunct, binding.slot, shape);
+        if ('refusal' in planned) return null;
+        filter = conjoin(filter, planned.pred);
+      }
+      if (!edges.length) return null;
+      const index = leaves.length;
+      leaves.push({ count: { entity, binding: binding.name, edges, filter } });
+      return { p: 'leaf', index };
+    }
     if (child.kind === 'path') {
       const binding = child.external === true ? undefined : byName.get(child.rootSlot);
       if (binding === undefined) return null;
@@ -3122,6 +3190,10 @@ export function planEntityPredicate(node, slot, shape) {
     if (!('ref' in pred) || pred.ref === null) return pred;
     const canonical = canonicalOf(pred.ref.segments);
     const flavored = shape.entityFlavors.get(canonical);
+    if (shape.columnOnly && (flavored === undefined || flavored.unsafe || flavored.nullPolicy === 'null')) {
+      blocked = refusal('physical', PREDICATE_REASONS.physicalCodec);
+      return pred;
+    }
     if (flavored === undefined) {
       // externals against DOC paths are not translated here (the
       // phase-A external forms assume the collection layout)
@@ -3131,7 +3203,8 @@ export function planEntityPredicate(node, slot, shape) {
       return { ...pred, ref: { ...pred.ref, flavor: 'entity-doc' } };
     }
     const ref = { ...pred.ref, column: flavored.column,
-      flavor: flavored.flavor, storage: flavored.storage, format: flavored.format };
+      flavor: flavored.flavor, storage: flavored.storage, format: flavored.format,
+      codec: flavored.codec, codecColumn: flavored.codecColumn, nullPolicy: flavored.nullPolicy };
     if (flavored.flavor === 'entity-epoch' && pred.p === 'cmp') {
       if ('ext' in pred.operand) {
         blocked = refusal(pred.op, ENTITY_REASONS.external);
@@ -3204,7 +3277,7 @@ function planEntityQueryCore(document, entities, mapping, operators) {
   if (root.kind !== 'flwor')
     return residual(root.kind, ENTITY_REASONS.notFlwor);
   if (root.fold !== null || root.letBindings.length > 0 || root.asChecks !== null
-    || root.groupby !== null || root.count !== null)
+    || root.count !== null)
     return residual('$let', KIND_REASONS.let);
 
   // bindings must each range over one entity's array
@@ -3222,6 +3295,19 @@ function planEntityQueryCore(document, entities, mapping, operators) {
     });
   }
   const byName = new Map(bindings.map((binding) => [binding.slot, binding]));
+  const group = root.groupby === null ? null : bindings.length === 1 && aggregate === null && !windows.length
+    ? planGeneralGrouping(root, bindings[0].slot, bindings[0].shape, entityPathRef) : null;
+  if (root.groupby !== null && group === null) return residual('$groupby', ENTITY_REASONS.projection);
+  if (group && [...group.keys, ...group.aggregates].some((entry) => entry.ref && entry.ref.flavor !== 'entity-column'))
+    return residual('$groupby', ENTITY_REASONS.projection);
+  // Integer accumulations carry a runtime exactness proof. Floating
+  // accumulations and date-codec validation need the decoded evaluator.
+  if (group && [...group.keys, ...group.aggregates].some((entry) => entry.ref
+    && (['date', 'datetime'].includes(entry.ref.codec)
+      || (['sum', 'avg'].includes(entry.fn) && entry.ref.type !== 'integer'))))
+    return residual('$groupby', ENTITY_REASONS.projection);
+  if (group?.order === 'first-seen' && entities.get(bindings[0].entity).physical?.keys.length > 1)
+    return residual('$groupby', ENTITY_REASONS.groupOrder);
   const conjuncts = root.where === null
     ? []
     : root.where.kind === 'op' && root.where.name === '$and'
@@ -3362,12 +3448,12 @@ function planEntityQueryCore(document, entities, mapping, operators) {
   // SHAPE the projection tree rebuilds from the bindings' members
   const retBinding = root.ret.kind === 'var' && root.ret.external !== true
     ? byName.get(root.ret.slot) : undefined;
-  const projection = retBinding === undefined
-    ? entityProjectionTree(root.ret, byName) : null;
-  if (retBinding === undefined && projection === null) {
+  const projection = retBinding === undefined && group === null
+    ? entityProjectionTree(root.ret, byName, entities, mapping) : null;
+  if (retBinding === undefined && projection === null && group === null) {
     reasons.push(refusal('$return', ENTITY_REASONS.projection));
   }
-  if (projection?.tree.p === 'leaf' && (aggregate === 'count' || windows.length > 0)) {
+  if (projection?.tree.p === 'leaf' && !projection.leaves[projection.tree.index].count && (aggregate === 'count' || windows.length > 0)) {
     const leaf = projection.leaves[projection.tree.index];
     const binding = bindings.find((entry) => entry.name === leaf.binding);
     filters.set(binding.slot, conjoin(filters.get(binding.slot),
@@ -3377,7 +3463,7 @@ function planEntityQueryCore(document, entities, mapping, operators) {
   // ordering over flavored refs of either binding
   let order = null;
   let orderPushed = true;
-  if (root.orderby !== null) {
+  if (root.orderby !== null && group === null) {
     const terms = [];
     for (const spec of root.orderby.specs) {
       const slot = spec.key.kind === 'path' ? spec.key.rootSlot : -1;
@@ -3389,6 +3475,7 @@ function planEntityQueryCore(document, entities, mapping, operators) {
       // (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.nullPolicy === 'null'
         || (ref.flavor === 'entity-doc' && admitsNull(binding.shape.schema, ref.segments))
         || spec.collation !== null || spec.collationName !== null) {
         orderPushed = false;
@@ -3401,7 +3488,7 @@ function planEntityQueryCore(document, entities, mapping, operators) {
   }
 
   const fullyPushed = whereFullyPushed && orderPushed
-    && (retBinding !== undefined || projection !== null);
+    && (retBinding !== undefined || projection !== null || group !== null);
   if (!fullyPushed) {
     return { analysis, mode: 'set', plan: null, referenced, reasons };
   }
@@ -3431,7 +3518,11 @@ function planEntityQueryCore(document, entities, mapping, operators) {
     plan: {
       planVersion: PLAN_VERSION,
       alg: bindings.length > 1 ? 'entity-join' : 'entity-select',
-      bindings: bindings.map((binding) => ({ name: binding.name, entity: binding.entity })),
+      bindings: bindings.map((binding) => ({ name: binding.name, entity: binding.entity,
+        ...(entities.get(binding.entity).physical == null ? {} : {
+          keys: mapping.entities[binding.entity].keys.map((key) =>
+            mapping.entities[binding.entity].columns.find((c) => c.name === key).physical),
+        }) })),
       // the FROM order and each binding's join conditions; `bindings`
       // stays in the DOCUMENT's order, which is the nested-loop order
       // the ORDER BY reproduces
@@ -3439,8 +3530,10 @@ function planEntityQueryCore(document, entities, mapping, operators) {
         binding: join.binding,
         on: join.on.map((edge) => ({
           op: edge.op ?? 'eq',
-          left: { binding: edge.left.binding.name, column: edge.left.ref.column },
-          right: { binding: edge.right.binding.name, column: edge.right.ref.column },
+          left: { binding: edge.left.binding.name, column: edge.left.ref.column,
+            ...(edge.left.ref.codec === undefined ? {} : { codec: edge.left.ref.codec }) },
+          right: { binding: edge.right.binding.name, column: edge.right.ref.column,
+            ...(edge.right.ref.codec === undefined ? {} : { codec: edge.right.ref.codec }) },
         })),
       })),
       filters: bindings.map((binding) => ({
@@ -3453,12 +3546,13 @@ function planEntityQueryCore(document, entities, mapping, operators) {
       })),
       window,
       aggregate,
+      group,
       ret: retBinding === undefined ? null : retBinding.name,
       // the projected shape, when the return is one: leaves that name
       // the binding they read from, and the tree the decoder rebuilds
       project: projection === null ? null : {
         tree: projection.tree,
-        leaves: projection.leaves.map((leaf) => ({ binding: leaf.binding, ref: leaf.ref })),
+        leaves: projection.leaves,
       },
     },
   };