@jarenjs/db 0.72.0 → 0.72.2

package/ARCHITECTURE.md

@@ -258,9 +258,11 @@ re-run unnamed rather than raised.
 
 Three normalizations, each forced by the wire rather than chosen:
 `int8` and `numeric` arrive as strings (they can exceed a double) and
-become JavaScript numbers, which is the same ceiling SQLite's INTEGER
-has; `json`/`jsonb` arrive parsed, because the client's type parsers are
-the host's configuration, and the row decoder reads text; and a
+become JavaScript numbers. An `int8` outside the safe integer range
+refuses with `JD2005`; allocated collection inserts decode `RETURNING`
+inside a transaction so a refused key rolls its row back. PostgreSQL
+sequences still advance on rollback. `json`/`jsonb` arrive parsed, because
+the client's type parsers are the host's configuration, and the row decoder reads text; and a
 JavaScript boolean is bound as 1 or 0, because a boolean member is 1 or
 0 in this mapping.
 
@@ -529,7 +531,7 @@ member as an array or an object **and nothing else** — §8.14 answers
 | `{$le\|$lt: [{$distance: [<path>, <literal>]}, r]}` | the same four comparisons against `circleBounds(probe, r)` | implied | every position within `r` metres lies inside the circle's box, which the kernel computes on the same sphere and the same `EARTH_RADIUS` the engine measures with — so the two cannot disagree by model. `$ge`/`$gt` is NOT promoted: no box narrows "farther than r" |
 | `{$starts-with: [{$geohash: [<path>, k]}, "<cell>"]}`, cell length ≤ k | `<c> IN ("<cell>")` or `<c> >= "<cell>" AND <c> < successor` | **exact** | the column HOLDS `$geohash(row, k)`, and geohash is a prefix code, so a prefix test on the expression is the same test on the column |
 | the same, cell length > k | the cell truncated to k | implied | the column can only confirm its own first k characters |
-| `{$exists: {$index-of: [{$geohash-neighbours: "<cell>"}, {$geohash: [<path>, k]}]}}`, cell length = k | `<c> IN (…the nine cells…)` | **exact** | the membership test compares whole strings and the column is exactly one of them. Nine cells, never one: two points ten metres apart can differ in the FIRST character of their cell (D7), so a single prefix is bucketing and only the neighbourhood is proximity |
+| `{$exists: {$index-of: [{$geohash-neighbours: "<cell>"}, {$geohash: [<path>, k]}]}}`, cell length = k | `<c> IS NULL OR <c> IN (…the nine cells…)` | **inexact** | Unbounded members remain candidates so the row predicate preserves the empty-search-item error. An explicit `$exists` guard excludes them safely. Nine cells cover neighbours across a cell boundary; one prefix does not. |
 
 **The proof is a proof about BOXES, not about SQL**, so the physical
 mapping (MODEL-FORMAT §2.1, `physical`) does not enter it: the same box

package/README.md

@@ -297,7 +297,9 @@ no continuation to emit.
   `$within`, a `$bbox-intersects`, a bounded `$distance` or a geohash
   probe over such a collection narrows **in SQLite** through the index
   and refines **in the engine**. `$bbox-intersects` and a geohash cell
-  test are exact and need no refinement; `$within` and a bounded
+  prefix test are exact and need no refinement; neighbourhood membership
+  retains unbounded candidates and preserves the engine's empty-item error.
+  `$within` and a bounded
   `$distance` push a bounding box the truth table proves they imply,
   and the exact predicate re-runs over the narrowed candidates —
   `explain().prefilters` says which, over what columns, and whether it
@@ -431,8 +433,10 @@ how.scanNarrative;
 The region arrives as a bound parameter: a GeoJSON object is not a
 value any database can bind, so what binds is one edge of its box per
 slot, computed at bind time from the same kernel the stored columns
-came from. `$bbox-intersects` and a geohash cell test are exact and
-need no refinement; `$within` and a bounded `$distance` push the box
+came from. `$bbox-intersects` and a geohash prefix no longer than the
+indexed cell are exact and need no refinement; neighbourhood membership
+refines to preserve errors on
+unbounded candidates. `$within` and a bounded `$distance` push the box
 they provably imply and re-run the exact predicate over the narrowed
 candidates. A circle that reaches a pole or crosses the antimeridian
 pushes **nothing** — there is no single box to push — and the answer is
@@ -1085,13 +1089,13 @@ disagree.
 <!--fact:live.eventTimeTable-->
 | view | maintained | re-run | ratio |
 |---|---:|---:|---:|
-| bucket (60 s ladder, mean), 1000 rows | 119 µs | 1.09 ms | 9.2× |
-| rolling (5 min window, mean), 1000 rows | 407 µs | 3.86 ms | 9.5× |
-| bucket (60 s ladder, mean), 10000 rows | 136 µs | 10.9 ms | 80.2× |
-| rolling (5 min window, mean), 10000 rows | 13.7 ms | 62.7 ms | 4.6× |
+| bucket (60 s ladder, mean), 1000 rows | 123 µs | 911 µs | 7.4× |
+| rolling (5 min window, mean), 1000 rows | 411 µs | 3.67 ms | 8.9× |
+| bucket (60 s ladder, mean), 10000 rows | 136 µs | 8.12 ms | 59.6× |
+| rolling (5 min window, mean), 10000 rows | 13.4 ms | 60.9 ms | 4.5× |
 <!--/fact-->
 
-The gain is <!--fact:live.eventTimeBand-->80.2× for the bucket and 4.6× for the rolling at 10,000 readings<!--/fact-->. A bucket
+The gain is <!--fact:live.eventTimeBand-->59.6× for the bucket and 4.5× for the rolling at 10,000 readings<!--/fact-->. A bucket
 view is nearly flat in the series length, because a write folds one
 bucket again and the rest of the ladder is untouched. A rolling view is
 not, and the table says so: its answer is one row per reading, so the

package/docs/HOSTS.md

@@ -6,6 +6,11 @@ capabilities are observed when the connection opens. The common oracle and
 lifecycle corpus is `test/db/store-hosts.test.js`; it checks values and coded
 errors across Node, worker, pool, wasm sessions and wasm journal fallback.
 
+Concurrent PostgreSQL first opens can race while creating the same collection
+or entity table. Each initialization transaction retries one catalog-creation
+collision after rollback, then re-reads and verifies the winning shape. Ordinary
+constraint failures remain errors, and a repeated collision refuses the open.
+
 ## Node workers
 
 ```js

package/docs/MIGRATION-FORMAT.md

@@ -107,6 +107,39 @@ and the column entry carries the width the value is packed to:
 
 ## 3. Planning and the widening/narrowing rule
 
+### Repairing a legacy spatial member expression
+
+SQLite derived spatial columns read members as JSON values, preserving strings
+and booleans as well as geometry objects and coordinate arrays. A legacy column
+declared with `json(jsonb_extract(...))` has different SQL and remains a
+`JD0002` at open; opening never rewrites an existing table. Rebuild those
+derived columns through an ordinary migration. The intermediate model below
+removes only spatial indexes; the two plans are combined into one transaction,
+including any R\*Tree trigger removal and backfill:
+
+```js
+const withoutSpatial = structuredClone(model);
+for (const collection of Object.values(withoutSpatial.collections ?? {})) {
+  collection.indexes = (collection.indexes ?? [])
+    .filter((index) => !['geohash', 'bbox'].includes(index.derive));
+}
+const remove = planMigration(model, withoutSpatial, { dialect: sqliteDialect }).migration;
+const restore = planMigration(withoutSpatial, model, { dialect: sqliteDialect }).migration;
+const repair = {
+  ...remove, id: 'spatial-member-json', to: restore.to,
+  steps: [...remove.steps, ...restore.steps],
+};
+await migrate({ driver, path }, [...previousMigrations, repair], { baseline, model });
+```
+
+Keep the historical baseline and full migration list. With no previous migrations,
+`baseline` is `model`. The logical model hash stays the same; the explicit
+artifact changes the physical expression. Shadow verification and final shape
+validation run normally, stored documents remain intact, and replay skips the
+recorded repair. The stored-column mapping does not need this repair.
+
+### Model differences
+
 `planMigration(fromModel, toModel, { dialect, id, derived })` produces
 `{ migration, report }` by diffing the two models' PHYSICAL plans. The
 from-model is the previous model — the previous model FILE, or, under

package/docs/MODEL-FORMAT.md

@@ -379,7 +379,7 @@ rather than degrading silently.
 
 | capability | value | mapping | drivers |
 |---|---|---|---|
-| `deterministicIndexableFunctions` | `true` | a **virtual generated column** whose expression calls a deterministic function the store registers at open — `jaren_geohash(<member>, <precision>)`, `jaren_bbox_w(<member>)`, … over `json(jsonb_extract("doc", '<path>'))` | `node`, `wasm` |
+| `deterministicIndexableFunctions` | `true` | a **virtual generated column** whose expression calls a deterministic function the store registers at open — `jaren_geohash(<member>, <precision>)`, `jaren_bbox_w(<member>)`, … over `json(("doc" -> '<path>'))` | `node`, `wasm` |
 | `deterministicIndexableFunctions` | `false` | a **stored column** the store writes on every insert, upsert and patch, computed in JavaScript from the same kernel call | `bun` |
 | `rtree` | `false` | a `derive: 'bbox'` column set that declared `physical: 'rtree'` (§2.1) is planned, created and verified as the **B-tree over its four columns**, and `explain().prefilters[].via` reports `'columns'` beside `store.capabilities.rtree === false` | any build without `ENABLE_RTREE` |
 
@@ -451,9 +451,18 @@ no positions at all, or one whose coordinates are not positions, which
 is what a non-finite coordinate becomes: JSON cannot carry `NaN`, so it
 arrives as `null` and is no longer a number.
 
+A string also has no position: an untyped member can store WKT or even the
+string `"[1,2]"` without interpreting it as a coordinate array. Virtual and
+stored columns both derive `NULL`. Existing SQLite expressions that passed raw
+SQL strings to `json()` need the explicit column repair described in
+[MIGRATION-FORMAT §3](MIGRATION-FORMAT.md#repairing-a-legacy-spatial-member-expression).
+
 The consequence is stated here rather than discovered later: **a row
-whose derived column is `NULL` is not found by a predicate pushed to
-that column.** For the spatial predicates the planner promotes
+whose derived column is `NULL` is not found by ordinary predicates pushed to
+that column.** Neighbourhood membership retains those rows as candidates and
+re-runs its predicate: `$index-of` raises for an empty search item, so discarding
+the row would hide that error. Guard the geohash with `$exists` before the
+membership test when unbounded rows should be excluded. For the other spatial predicates the planner promotes
 (ARCHITECTURE.md, "The implied conjunct") that is not a divergence —
 §8.14 measures a value by its representative position, and that
 position is missing in exactly the cases the box is, so `$within`,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/db",
   "private": false,
-  "version": "0.72.0",
+  "version": "0.72.2",
   "type": "module",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
@@ -84,9 +84,9 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.72.0",
-    "@jarenjs/json": "^0.72.0",
-    "@jarenjs/validate": "^0.72.0"
+    "@jarenjs/core": "^0.72.2",
+    "@jarenjs/json": "^0.72.2",
+    "@jarenjs/validate": "^0.72.2"
   },
   "bin": {
     "jaren-db": "./src/cli.js"

package/src/algebra.js

@@ -57,7 +57,7 @@ export const PLAN_VERSION = 2;
  *   { p: 'udf', name: string, key: string } |
  *   { p: 'bboxOverlap', columns: { w: string, s: string, e: string,
  *     n: string }, probe: { box: number[] } | { ext: string } } |
- *   { p: 'cellIn', column: string, cells: string[] } |
+ *   { p: 'cellIn', column: string, cells: string[], keepEmpty?: boolean } |
  *   { p: 'cellPrefix', column: string, prefix: string } |
  *   { p: 'interval', columns: { start: string, end: string },
  *     probe: { from: number, to: number } } |
@@ -75,6 +75,9 @@ export const PLAN_VERSION = 2;
  *   — but each is TOTAL through its own `IS NOT NULL`, so a row with no
  *   box or no cell answers FALSE rather than SQL's NULL and negation
  *   still composes classically.
+ *   A neighbourhood membership uses `keepEmpty: true` instead: NULL
+ *   cells remain candidates so its residual preserves the query's error
+ *   for an empty search item. Such a predicate is never exact.
  *
  *   `colCmp` is the same idea one comparison wide: a bound over a
  *   DECLARED column, with no `json_type` beside it. The planner builds

package/src/derive.js

@@ -257,7 +257,8 @@ export function memberAt(doc, segments) {
 /**
  * Parse the JSON text a derived column's expression hands the function.
  * SQLite passes SQL NULL for a member the document does not have, and
- * `json()` of an extracted member is unambiguous JSON text otherwise.
+ * the JSON-valued extraction preserves the member's encoding otherwise,
+ * including quotes around strings and the spelling of booleans.
  * @param {any} text
  * @returns {any} the value, or `undefined` when there is none
  */

package/src/dialect.js

@@ -137,6 +137,7 @@ function normalizeCapabilities(declared) {
  *   limitClause: (limit: number, offset?: number) => string,
  *   jsonPathText: (segments: JsonPathSegment[]) => string | null,
  *   jsonExtract: (columnSql: string, pathText: string, kind?: string) => string,
+ *   isCreateRace?: (error: any) => boolean,
  *   derivedExpression?: (memberSql: string, column: { derive: string,
  *     precision?: number, component?: string, dims?: number }) => string,
  *   jsonSet: (exprSql: string, pathText: string, valueSql: string) => string,
@@ -532,6 +533,7 @@ export function createDialect(spec) {
     limitClause: spec.limitClause,
     jsonPathText: spec.jsonPathText,
     jsonExtract: spec.jsonExtract,
+    isCreateRace: spec.isCreateRace,
     /**
      * The expression a DERIVED column is generated from: the member at
      * the index path, as JSON text, handed to the deterministic
@@ -542,7 +544,7 @@ export function createDialect(spec) {
      * @returns {string}
      */
     derivedColumn: (docColumnSql, pathText, column) => spec.derivedExpression(
-      spec.jsonText(spec.jsonExtract(docColumnSql, pathText)), column),
+      spec.jsonText(spec.jsonExtract(docColumnSql, pathText, 'json')), column),
     jsonSet: spec.jsonSet,
     jsonRemove: spec.jsonRemove,
     jsonAppend: spec.jsonAppend,

package/src/dialects/postgres.js

@@ -442,6 +442,11 @@ export function postgresDialect(options = undefined) {
       : `LIMIT ${limit === null ? 'ALL' : limit}`),
     jsonPathText,
     jsonExtract,
+    // Concurrent first opens can both observe an absent relation before
+    // either CREATE commits. Ordinary unique violations remain failures.
+    isCreateRace: (error) => error?.code === '42P07' || error?.code === '23505'
+      && (error.constraint === 'pg_type_typname_nsp_index' && error.table === 'pg_type'
+        || error.constraint === 'pg_class_relname_nsp_index' && error.table === 'pg_class'),
     // a DERIVED column's expression names a function the HOST supplies;
     // this dialect creates none and assumes none. Every driver this
     // package ships for PostgreSQL declares

package/src/dialects/sqlite.js

@@ -299,8 +299,12 @@ export const sqliteDialect = createDialect({
     ? `LIMIT ${limit === null ? -1 : limit} OFFSET ${offset}`
     : `LIMIT ${limit === null ? -1 : limit}`),
   jsonPathText,
-  jsonExtract: (columnSql, pathText) =>
-    `jsonb_extract(${columnSql}, ${stringLiteral(pathText)})`,
+  // JSON-valued consumers need the encoded member, including quotes around
+  // strings and the original boolean spelling; jsonb_extract returns SQL
+  // scalars for these and json() cannot recover their JSON representation.
+  jsonExtract: (columnSql, pathText, kind) => kind === 'json'
+    ? `(${columnSql} -> ${stringLiteral(pathText)})`
+    : `jsonb_extract(${columnSql}, ${stringLiteral(pathText)})`,
   // a DERIVED column's expression: the member as JSON text handed to
   // the deterministic function the store registers at open. The
   // precision is a LITERAL, not a parameter — a generated column's

package/src/drivers/postgres.js

@@ -20,8 +20,8 @@
  *
  *  - `int8` and `numeric` arrive as STRINGS, because they can exceed
  *    what a double holds. The store's contract is JavaScript numbers —
- *    the same ceiling SQLite's INTEGER has — so they are converted, and
- *    a value past 2^53 loses precision here exactly as it would there.
+ *    so they are converted. An `int8` outside the safe integer range
+ *    refuses rather than returning a rounded key or count.
  *  - `json`/`jsonb` arrive PARSED, because the client's type parsers
  *    are the host's configuration. Every document read is already
  *    `::text` (the dialect's `jsonText`), but a graph load's built
@@ -34,7 +34,7 @@
 
 import { chain, openConnection, baseCapabilities } from '../driver.js';
 import { postgresDialect } from '../dialects/postgres.js';
-import { DbCompileError } from '../errors.js';
+import { DbCompileError, DbRuntimeError } from '../errors.js';
 
 export { postgresDialect, IDENTIFIER_BYTES } from '../dialects/postgres.js';
 
@@ -45,7 +45,7 @@ export const POSTGRES_FLOOR = 160000;
 /** Types the wire hands back as text because they can exceed a double,
  * and the two it hands back as text for width alone. The store's
  * contract is JavaScript numbers throughout. */
-const NUMERIC_OIDS = new Set([20, 21, 23, 26, 700, 701, 1700]);
+const NUMERIC_OIDS = new Set([21, 23, 26, 700, 701, 1700]);
 /** `json` and `jsonb`: parsed by the client unless the host said
  * otherwise, and the row decoder reads text. */
 const JSON_OIDS = new Set([114, 3802]);
@@ -73,6 +73,17 @@ let statementSequence = 0;
  *   is already what the store reads
  */
 function converterFor(dataTypeID) {
+  if (dataTypeID === 20) {
+    return (value) => {
+      if (value === null || value === undefined) return value;
+      const number = Number(value);
+      if (!Number.isSafeInteger(number)) {
+        throw new DbRuntimeError('JD2005',
+          `PostgreSQL int8 value '${String(value)}' is outside the safe JavaScript integer range`);
+      }
+      return number;
+    };
+  }
   if (NUMERIC_OIDS.has(dataTypeID)) {
     return (value) => (value === null || value === undefined ? value : Number(value));
   }

package/src/emit.js

@@ -393,6 +393,10 @@ export function emitPlan(plan, dialect, physical) {
         // per row.
         const column = q(pred.column);
         const list = pred.cells.map((cell) => param({ literal: cell })).join(', ');
+        // An empty membership search item raises in the query engine. The
+        // candidate fetch must retain it for the original row predicate.
+        if (pred.keepEmpty === true) return pred.cells.length === 0 ? `${column} IS NULL`
+          : `(${column} IS NULL OR ${column} IN (${list}))`;
         return `(${column} IS NOT NULL AND ${column} IN (${list}))`;
       }
       case 'cellPrefix': {

package/src/plan.js

@@ -505,6 +505,8 @@ const SPATIAL_REASONS = {
   distance: 'a geodesic-circle box pre-filter is pushed; the exact distance refines in the engine',
   prefix: "a cell-range pre-filter over the derived column's precision is pushed; "
     + 'the longer prefix refines in the engine',
+  membership: 'the cell pre-filter retains unbounded members; the engine preserves '
+    + 'the membership error when its search item is empty',
   noIndex: 'no derived spatial index on this member covers the predicate '
     + '(declare indexes[].derive on it)',
   notGeographic: 'spatial predicates translate only over a member the schema types as an '
@@ -856,10 +858,12 @@ function planCellPrefix(node, itSlot, shape) {
  * the cells inline, where the planner can see them.
  *
  * Recognized: `{$exists: {$index-of: [{$geohash-neighbours: "cell"},
- * {$geohash: [path, k]}]}}`. Exact only when the cell's length IS k —
+ * {$geohash: [path, k]}]}}`. Admitted only when the cell's length IS k —
  * the membership test compares whole strings, so any other length makes
  * the document's own predicate constantly false and the promotion would
- * be answering a different question.
+ * be answering a different question. Unbounded rows remain candidates:
+ * the engine's membership raises on an empty search item, so the original
+ * predicate must still run even when the column covers whole cell strings.
  * @param {any} node
  * @param {number} itSlot
  * @param {any} shape
@@ -878,9 +882,26 @@ function planCellNeighbourhood(node, itSlot, shape) {
   const cells = cellNeighbourhood(cell.value);
   if (cells.length === 0)
     return { refusal: refusal('$geohash-neighbours', SPATIAL_REASONS.operand) };
-  return promotion({ p: 'cellIn', column: derivation.column, cells },
+  return promotion({ p: 'cellIn', column: derivation.column, cells, keepEmpty: true },
     { construct: '$geohash-neighbours', via: 'columns', columns: [derivation.column],
-      exact: true });
+      exact: false }, [refusal('$geohash-neighbours', SPATIAL_REASONS.membership)]);
+}
+
+/** Error candidates cannot be discarded by a different pushed conjunct. */
+function neighbourhoodErrorColumns(node, itSlot, shape, columns = new Set()) {
+  if (node === null || typeof node !== 'object') return columns;
+  if (node.kind === 'op' && node.name === '$index-of'
+    && node.args[0]?.name === '$geohash-neighbours') {
+    const derivation = geohashDerivation(node.args[1], itSlot, shape, '$geohash-neighbours');
+    if (!('refusal' in derivation)) columns.add(derivation.column);
+  }
+  for (const value of Object.values(node)) {
+    if (Array.isArray(value)) {
+      for (const child of value) neighbourhoodErrorColumns(child, itSlot, shape, columns);
+    }
+    else if (value !== null && typeof value === 'object') neighbourhoodErrorColumns(value, itSlot, shape, columns);
+  }
+  return columns;
 }
 
 // ————— The k-nearest promotion: an ORDERING the column pre-filters —————
@@ -2365,6 +2386,21 @@ function planFlwor(node, shape, rawFlwor, udfHook) {
     }
   }
 
+  // A later conjunct must not hide an earlier membership error. Retain
+  // every potentially empty search row through the combined SQL filter;
+  // the original WHERE then decides whether short-circuiting reaches it.
+  const errorColumns = neighbourhoodErrorColumns(node.where, itSlot, shape);
+  if (errorColumns.size > 0 && plan.filter !== null) {
+    if (!(plan.filter.p === 'cellIn' && plan.filter.keepEmpty === true
+      && errorColumns.size === 1 && errorColumns.has(plan.filter.column))) {
+      plan.filter = { p: 'or', items: [plan.filter, ...[...errorColumns].map((column) =>
+        ({ p: 'cellIn', column, cells: [], keepEmpty: true }))] };
+    }
+    whereFullyPushed = false;
+    if (!reasons.some((entry) => entry.reason === SPATIAL_REASONS.membership))
+      reasons.push(refusal('$geohash-neighbours', SPATIAL_REASONS.membership));
+  }
+
   // ORDER BY: all terms or none — a partially pushed ordering is wrong.
   // A k-nearest ordering is the third outcome: not pushed, but
   // recognized for the column to pre-filter (the reason is the

package/src/store.js

@@ -450,12 +450,19 @@ function wrapWriteError(error, plan, collection, docPath, key) {
  * open nothing else holds the connection.
  * @param {any} connection
  * @param {() => any} fn - value-or-promise
+ * @param {boolean} [retry] - one retry for a concurrent catalog creation
  * @returns {any} value-or-promise
  */
-function immediately(connection, fn) {
+function immediately(connection, fn, retry = true) {
   const dialect = connection.dialect;
   const commit = (value) => chain(connection.exec(dialect.tx.commit), () => value);
-  const rollback = (error) => chain(connection.exec(dialect.tx.rollback), () => { throw error; });
+  const rollback = (error) => chain(connection.exec(dialect.tx.rollback), () => {
+    // The winner's CREATE has committed before a catalog collision returns.
+    // Re-read and verify that shape in a fresh transaction, once per bracket;
+    // collection and entity creation can race independently during one open.
+    if (retry && dialect.isCreateRace?.(error) === true) return immediately(connection, fn, false);
+    throw error;
+  });
   return chain(connection.exec(dialect.tx.beginImmediate), () => {
     let out;
     try {
@@ -673,6 +680,14 @@ function collectionCore(connection, collection, plan, validate, queryState, stor
         (error) => wrapWriteError(error, plan, collection.name, collection.docPath, key)));
   };
 
+  // RETURNING is decoded after the server has inserted the row. Keep
+  // decoding in the same transaction so an unrepresentable allocated
+  // key refuses without committing a document the caller cannot address.
+  const insertAllocated = (doc) => connection.transaction(() => chain(
+    runWrite('insertAllocated', dialect.dml.insertAllocated(shape),
+      [JSON.stringify(doc), ...derivedFor(doc)], undefined, true),
+    (row) => row.key));
+
   const core = {
     stats: () => ({ ...stats, ...engine.stats() }),
     model: collection,
@@ -694,12 +709,7 @@ function collectionCore(connection, collection, plan, validate, queryState, stor
     insert(doc) {
       checkValid(doc);
       const key = resolveWriteKey(doc, undefined);
-      if (key === null) {
-        return chain(
-          runWrite('insertAllocated', dialect.dml.insertAllocated(shape),
-            [JSON.stringify(doc), ...derivedFor(doc)], undefined, true),
-          (row) => row.key);
-      }
+      if (key === null) return insertAllocated(doc);
       return chain(
         runWrite('insert', dialect.dml.insert(shape),
           [key, JSON.stringify(doc), ...derivedFor(doc)], key, false),
@@ -708,12 +718,7 @@ function collectionCore(connection, collection, plan, validate, queryState, stor
     put(doc, explicitKey) {
       checkValid(doc);
       const key = resolveWriteKey(doc, explicitKey);
-      if (key === null) {
-        return chain(
-          runWrite('insertAllocated', dialect.dml.insertAllocated(shape),
-            [JSON.stringify(doc), ...derivedFor(doc)], undefined, true),
-          (row) => row.key);
-      }
+      if (key === null) return insertAllocated(doc);
       return chain(
         runWrite('upsert', dialect.dml.upsert(shape),
           [key, JSON.stringify(doc), ...derivedFor(doc)], key, false),