@jarenjs/db 0.49.2 → 0.66.1

package/src/tracker.js

@@ -8,29 +8,61 @@
  * snapshot against current with the suite's own diff engine and plans
  * the MINIMAL set of parameterised statements: scalar/epoch/foreign-
  * key column writes, `jsonb_set`/`jsonb_remove` chains for document
- * paths, join-table synchronisation for many-to-many members, and a
- * counted whole-row fallback for anything untranslatable.
+ * paths, join-table synchronisation for many-to-many members — by the
+ * key-set difference a `put` implies, or by an explicit `link`/`unlink`
+ * delta resolved against the join table at save time — and a counted
+ * whole-row fallback for anything untranslatable.
  *
  * Ordering never violates a foreign key mid-transaction: inserts run
  * parent-first, deletes child-first, updates in between, join rows
  * after both endpoints exist. A foreign-key cycle among the entities
  * being inserted or deleted is `JD0040`, reported, never a deadlock.
- * The whole save is one transaction; the tracker is mutated ONLY
- * after commit, so a failed save leaves it exactly as it was and a
- * retry is possible.
+ * The whole save is one transaction, and the tracker is mutated only
+ * after its statements have run — so a save that FAILS leaves the
+ * tracker exactly as it was and a retry is possible. A save that
+ * SUCCEEDS inside a larger transaction advances at once (inside it, the
+ * database does hold those rows, and every later plan and optimistic
+ * guard has to agree), and registers the withdrawal of that advance
+ * against the scope that owns the connection: an enclosing rollback
+ * takes it back, so the retry plans the same statements again rather
+ * than reporting a success it never had.
  */
 
 import { createJSONPatch } from '@jarenjs/json/patch';
 import { parseJSONPointer } from '@jarenjs/json/pointer';
 
 import { DbCompileError, DbRuntimeError } from './errors.js';
-import { chain } from './driver.js';
+import { chain, attempt } from './driver.js';
 import { translatePatch } from './patch-sql.js';
 
 /** Rows per batched INSERT: bounded by the portable parameter budget. */
 export const BATCH_PARAM_BUDGET = 900;
 export const BATCH_ROW_BOUND = 100;
 
+/**
+ * The target keys a many-to-many membership array names: a key, or a
+ * document carrying the target's key. One reading for the unit of work
+ * and for `create()`, so the two attach the same rows.
+ * @param {any} value - the member's value
+ * @param {string} targetKey - the target entity's key property
+ * @param {string} member
+ * @param {(reason: string) => Error} refuse
+ * @returns {(string | number)[]}
+ */
+export function membershipKeys(value, targetKey, member, refuse) {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) throw refuse(`'${member}' must be an array to synchronise its join table`);
+  return value.map((element) => {
+    const key = typeof element === 'string' || typeof element === 'number'
+      ? element
+      : element !== null && typeof element === 'object'
+        ? element[targetKey] : undefined;
+    if (typeof key !== 'string' && typeof key !== 'number')
+      throw refuse(`an element of '${member}' carries no usable '${targetKey}' key`);
+    return key;
+  });
+}
+
 const UNIT_SEPARATOR = '';
 
 /**
@@ -70,10 +102,16 @@ export function createTracker(context) {
   const records = new Map();
   /** @type {Map<string, any>} */
   const removals = new Map();
+  /** Pending membership deltas (§11.7), one per entity, own key and
+   * many-to-many member: the targets to link and the targets to unlink.
+   * @type {Map<string, { entity: string, member: string, ownKey: string | number,
+   *   links: Set<string | number>, unlinks: Set<string | number> }>} */
+  const memberships = new Map();
   let pendingSequence = 0;
 
-  const keyOf = (entityName, parts) =>
-    `${entityName}${UNIT_SEPARATOR}${parts.join(UNIT_SEPARATOR)}`;
+  // Keys may contain the membership separator themselves. Encode the
+  // whole tuple so its component boundaries and entity remain distinct.
+  const keyOf = (entityName, parts) => JSON.stringify([entityName, ...parts]);
 
   const recordKeyFor = (entityName, doc) => {
     const plan = coreFor(entityName).plan;
@@ -89,6 +127,12 @@ export function createTracker(context) {
       collection: entityName,
     });
 
+  /** A membership write needs the entity's own key: an `auto` key is
+   * allocated by the save, so a pending insert has none to attach to. */
+  const needsOwnKey = (entityName, member, verb) => contractError(entityName,
+    `'${member}' membership needs the entity's own key at ${verb} time — `
+    + 'save the entity first, then attach');
+
   const register = (entityName, doc) => {
     deepFreeze(doc);
     const key = recordKeyFor(entityName, doc);
@@ -169,6 +213,86 @@ export function createTracker(context) {
     });
   };
 
+  /** The pending insert a caller is holding, found by the identity of
+   * the document `add()` handed back: a record whose key the save has
+   * yet to allocate has nothing else to be found by. */
+  const pendingInsertHolding = (entityName, doc) => {
+    for (const record of records.values()) {
+      if (record.pendingInsert === true && record.entity === entityName
+        && record.current === doc) return record;
+    }
+    return undefined;
+  };
+
+  /** What a join op and its membership delta are filed under: the own
+   * key once there is one, and the pending record's own identity while
+   * the save has yet to allocate it. */
+  const ownToken = (entityName, ownKey, ownRecord) => (ownRecord === undefined
+    ? keyOf(entityName, [ownKey])
+    : ownRecord.pendingKey);
+
+  /**
+   * The pending membership delta a `link`/`unlink` addresses (§11.7):
+   * the member must be a many-to-many relation of the entity; the own
+   * key is read from a key or a document; the target is a key or a
+   * document carrying the target's key — the reading a membership array
+   * gets, so the two attach the same rows.
+   *
+   * A document whose key the save allocates carries none to attach to,
+   * so the delta is filed against the pending INSERT it belongs to and
+   * the join row takes the key that insert returns.
+   */
+  const membershipOf = (entityName, own, member, target, verb) => {
+    const plan = coreFor(entityName).plan;
+    const relation = entities.get(entityName).properties.get(member)?.relation;
+    if (relation === undefined || relation.kind !== 'manyToMany') {
+      throw contractError(entityName, relation === undefined
+        ? `'${member}' is not a relation member of '${entityName}' — ${verb}() attaches a `
+          + 'many-to-many membership through its join table'
+        : `'${member}' is a ${relation.kind} relation — ${verb}() attaches many-to-many `
+          + "memberships only; write the related entity's foreign key instead");
+    }
+    let ownKey;
+    let ownRecord;
+    if (own !== null && typeof own === 'object' && !Array.isArray(own)) {
+      ownKey = own[plan.keys[0]];
+      if (typeof ownKey !== 'string' && typeof ownKey !== 'number') {
+        ownRecord = pendingInsertHolding(entityName, own);
+        if (ownRecord === undefined) throw needsOwnKey(entityName, member, `${verb}()`);
+        ownKey = undefined;
+      }
+    }
+    else {
+      ownKey = coreFor(entityName).normalizeKey(own)[0];
+    }
+    const targetKey = mapping.entities[relation.to].keys[0];
+    const [key] = membershipKeys([target], targetKey, member,
+      (reason) => contractError(entityName, reason));
+    const id = `${ownToken(entityName, ownKey, ownRecord)}${UNIT_SEPARATOR}${member}`;
+    let pending = memberships.get(id);
+    if (pending === undefined) {
+      pending = { entity: entityName, member, ownKey, ownRecord,
+        links: new Set(), unlinks: new Set() };
+      memberships.set(id, pending);
+    }
+    return { pending, key };
+  };
+
+  /** Attach one membership (local, synchronous); the last word on one
+   * target wins, so `unlink` after `link` means unlink. */
+  const link = (entityName, own, member, target) => {
+    const { pending, key } = membershipOf(entityName, own, member, target, 'link');
+    pending.unlinks.delete(key);
+    pending.links.add(key);
+  };
+
+  /** Detach one membership (local, synchronous). */
+  const unlink = (entityName, own, member, target) => {
+    const { pending, key } = membershipOf(entityName, own, member, target, 'unlink');
+    pending.links.delete(key);
+    pending.unlinks.add(key);
+  };
+
   const counts = () => {
     let pendingInserts = 0;
     for (const record of records.values()) {
@@ -178,6 +302,7 @@ export function createTracker(context) {
       tracked: records.size - pendingInserts,
       pendingInserts,
       pendingDeletes: removals.size,
+      pendingMemberships: memberships.size,
     };
   };
 
@@ -275,29 +400,31 @@ export function createTracker(context) {
     return { columnSets, docBuild, m2mMembers, fallback };
   };
 
+  /** The join-table endpoints a many-to-many member writes through. The
+   * endpoint columns come from the mapping, never from the join table's
+   * NAME: an entity name with an underscore, or a `through` name, does
+   * not split into its endpoints. */
+  const joinEndpoints = (entityName, member) => {
+    const relation = entities.get(entityName).properties.get(member).relation;
+    const join = mapping.joinTables[relation.joinTable];
+    const own = join.left.entity === entityName ? join.left : join.right;
+    const target = own === join.left ? join.right : join.left;
+    return {
+      entity: entityName,
+      member,
+      joinTable: relation.joinTable,
+      ownColumn: own.column,
+      targetColumn: target.column,
+      tableColumns: [join.left.column, join.right.column],
+      targetKey: mapping.entities[relation.to].keys[0],
+    };
+  };
+
   /** Compute a many-to-many member's join-row difference by key sets. */
   const joinDiff = (entityName, before, after, ownKey, member) => {
-    const entity = entities.get(entityName);
-    const relation = entity.properties.get(member).relation;
-    const targetKey = mapping.entities[relation.to].keys[0];
-    const extract = (value) => {
-      if (value === undefined || value === null) return [];
-      if (!Array.isArray(value)) {
-        throw contractError(entityName,
-          `'${member}' must be an array to synchronise its join table`);
-      }
-      return value.map((element) => {
-        const key = typeof element === 'string' || typeof element === 'number'
-          ? element
-          : element !== null && typeof element === 'object'
-            ? element[targetKey] : undefined;
-        if (typeof key !== 'string' && typeof key !== 'number') {
-          throw contractError(entityName,
-            `an element of '${member}' carries no usable '${targetKey}' key`);
-        }
-        return key;
-      });
-    };
+    const endpoints = joinEndpoints(entityName, member);
+    const extract = (value) => membershipKeys(value, endpoints.targetKey, member,
+      (reason) => contractError(entityName, reason));
     // a snapshot that never LOADED the member knows nothing about the
     // current membership — treating unknown as empty would re-insert
     // existing rows (a UNIQUE violation the seeded corpus found); the
@@ -307,15 +434,27 @@ export function createTracker(context) {
       ? null
       : [...new Set(extract(memberValue))];
     return {
-      joinTable: relation.joinTable,
-      ownColumn: `${entityName}_key`,
-      targetColumn: `${relation.to}_key`,
+      ...endpoints,
       ownKey,
       beforeKeys,
       afterKeys: [...new Set(extract(after[member]))],
     };
   };
 
+  /** A pending `link`/`unlink` delta as a join op. Its baseline is the
+   * join table as read at save time, so linking a member that exists
+   * and unlinking one that does not are no-ops — the two-run property. */
+  const membershipDelta = (pending) => ({
+    ...joinEndpoints(pending.entity, pending.member),
+    ownKey: pending.ownKey,
+    ownRecord: pending.ownRecord,
+    // a row the save is about to INSERT has no memberships to read: the
+    // key does not exist yet, so its baseline is empty rather than unknown
+    beforeKeys: pending.ownRecord === undefined ? null : [],
+    links: [...pending.links],
+    unlinks: [...pending.unlinks],
+  });
+
   /** Relation members riding a pending INSERT: many-to-many becomes
    * join rows; anything else refuses — projections are not state. */
   const insertRelationOps = (record) => {
@@ -334,12 +473,16 @@ export function createTracker(context) {
           + 'projection, not stored state; add the related entities themselves');
       }
       const ownKey = record.current[plan.keys[0]];
-      if (typeof ownKey !== 'string' && typeof ownKey !== 'number') {
-        throw contractError(record.entity,
-          `'${property.name}' membership needs the entity's own key at `
-          + 'add() time — save the entity first, then attach');
-      }
-      ops.push(joinDiff(record.entity, null, record.current, ownKey, property.name));
+      const known = typeof ownKey === 'string' || typeof ownKey === 'number';
+      if (!known && plan.autoKey === null)
+        throw needsOwnKey(record.entity, property.name, 'add()');
+      // the key this row will have is the one its INSERT returns, so the
+      // join row is planned against the record and takes the key at run time
+      ops.push({
+        ...joinDiff(record.entity, null, record.current,
+          known ? ownKey : undefined, property.name),
+        ownRecord: known ? undefined : record,
+      });
     }
     return ops;
   };
@@ -352,6 +495,10 @@ export function createTracker(context) {
     const updates = [];
     /** @type {any[]} */
     const joinOps = [];
+    /** Records this save advances through their join table alone: they
+     * carry no statement of their own, and the commit still settles
+     * them, so the undo delta has to know about them. @type {any[]} */
+    const joinOnly = [];
     let fallbacks = 0;
     const unversioned = new Set();
 
@@ -368,6 +515,10 @@ export function createTracker(context) {
         continue;
       }
       if (record.current === record.snapshot) continue;
+      // a record with a pending removal is deleted, not updated: planning
+      // both bumped the version on the UPDATE and left the DELETE's
+      // snapshot guard matching nothing (JD2040), so the row survived
+      if (removals.has(recordKeyFor(record.entity, record.snapshot) ?? '')) continue;
       // probe before stamping: an update stamp must never turn a
       // deep-equal replacement into a phantom write
       if (createJSONPatch(record.snapshot, record.current).length === 0) continue;
@@ -380,7 +531,10 @@ export function createTracker(context) {
       if (parts.columnSets.size === 0 && parts.docBuild === null
         && !parts.fallback) {
         // nothing but join-table changes (or a no-op put)
-        if (parts.m2mMembers.size > 0) record.joinOnly = true;
+        if (parts.m2mMembers.size > 0) {
+          record.joinOnly = true;
+          joinOnly.push(record);
+        }
         else record.stamped = undefined;
         continue;
       }
@@ -397,6 +551,23 @@ export function createTracker(context) {
         unversioned.add(removal.entity);
     }
 
+    // a link/unlink beside a put-based synchronisation of the SAME member
+    // folds into that op's key set: one intent per entity, own key and
+    // member, never two statements racing for one row
+    const synced = new Map(joinOps.map((op) =>
+      [`${ownToken(op.entity, op.ownKey, op.ownRecord)}${UNIT_SEPARATOR}${op.member}`, op]));
+    for (const [id, pending] of memberships) {
+      const diff = synced.get(id);
+      if (diff === undefined) {
+        joinOps.push(membershipDelta(pending));
+        continue;
+      }
+      const after = new Set(diff.afterKeys);
+      for (const key of pending.unlinks) after.delete(key);
+      for (const key of pending.links) after.add(key);
+      diff.afterKeys = [...after];
+    }
+
     // resolve unknown membership baselines, then finalize each op
     const resolveJoins = (i) => {
       if (i >= joinOps.length) return null;
@@ -413,6 +584,11 @@ export function createTracker(context) {
     const finalizeJoins = () => {
       for (const op of joinOps) {
         const before = new Set(op.beforeKeys);
+        if (op.links !== undefined) {
+          op.added = op.links.filter((key) => !before.has(key));
+          op.removed = op.unlinks.filter((key) => before.has(key));
+          continue;
+        }
         const after = new Set(op.afterKeys);
         op.added = op.afterKeys.filter((key) => !before.has(key));
         op.removed = op.beforeKeys.filter((key) => !after.has(key));
@@ -525,7 +701,10 @@ export function createTracker(context) {
             + `(${q(op.ownColumn)}, ${q(op.targetColumn)}) VALUES `
             + op.added.map((_, i) => `(${parameterAt(i * 2 + 1)}, ${parameterAt(i * 2 + 2)})`).join(', ');
           statements.push({
-            kind: 'join-insert', entity: op.joinTable, sql,
+            kind: 'join-insert', entity: op.joinTable, sql, tableColumns: op.tableColumns,
+            // an own key the save has yet to allocate is filled in from the
+            // insert's RETURNING, which the ordering above guarantees has run
+            ownFrom: op.ownRecord,
             params: op.added.flatMap((key) => [op.ownKey, key]),
             joinRows: op.added.map((key) => ({
               own: op.ownKey, target: key,
@@ -535,7 +714,7 @@ export function createTracker(context) {
         }
         for (const key of op.removed) {
           statements.push({
-            kind: 'join-delete', entity: op.joinTable,
+            kind: 'join-delete', entity: op.joinTable, tableColumns: op.tableColumns,
             sql: `DELETE FROM ${q(op.joinTable)} WHERE ${q(op.ownColumn)} = ${parameterAt(1)} `
               + `AND ${q(op.targetColumn)} = ${parameterAt(2)}`,
             params: [op.ownKey, key],
@@ -567,7 +746,7 @@ export function createTracker(context) {
         }
       }
 
-      return { statements, fallbacks, unversioned: [...unversioned].sort() };
+      return { statements, fallbacks, joinOnly, unversioned: [...unversioned].sort() };
     };
     return chain(resolveJoins(0), assemble);
   };
@@ -608,6 +787,15 @@ export function createTracker(context) {
     const next = (i) => {
       if (i >= statements.length) return report;
       const statement = statements[i];
+      // a join row whose own key the save allocates: the INSERT that
+      // allocates it has already run (inserts precede join rows), so the
+      // key is on the record by now
+      if (statement.ownFrom !== undefined) {
+        const ownKey = statement.ownFrom.allocatedKey;
+        statement.params = statement.joinRows.flatMap(
+          (/** @type {any} */ row) => [ownKey, row.target]);
+        for (const row of statement.joinRows) row.own = ownKey;
+      }
       return chain(connection.prepare(statement.sql), (prepared) => {
         if (statement.kind === 'insert' && statement.returning === true) {
           let fetched;
@@ -623,6 +811,9 @@ export function createTracker(context) {
             // test, not assumed silently)
             const keys = rows.map((row) => row.key).sort((a, b) => a - b);
             statement.generatedKeys = keys;
+            // a join row planned against one of these records reads its
+            // key from here, before the commit phase re-keys anything
+            statement.records.forEach((record, at) => { record.allocatedKey = keys[at]; });
             report.inserted += statement.records.length;
             report.statements.push({ sql: statement.sql, rows: statement.records.length });
             return next(i + 1);
@@ -633,14 +824,8 @@ export function createTracker(context) {
             ? captureJoinDelete(statement.entity, statement.removal.parts)
             : null,
           () => {
-        let ran;
-        try {
-          ran = prepared.run(statement.params);
-        }
-        catch (error) {
-          throw wrapDb(error, statement);
-        }
-        return chain(ran, (outcome) => {
+        return chain(attempt(() => prepared.run(statement.params),
+          (error) => wrapDb(error, statement)), (outcome) => {
           const changed = Number(outcome?.changes ?? 0);
           report.statements.push({ sql: statement.sql, rows: changed });
           if (statement.kind === 'insert') report.inserted += statement.records.length;
@@ -663,21 +848,116 @@ export function createTracker(context) {
     return next(0);
   };
 
-  /** Commit phase: only reached after the transaction succeeded. */
-  const commit = (statements) => {
+  /**
+   * The tracker state a save's commit will advance, exactly as it stands
+   * before the save runs: the map slot behind every record the commit
+   * may re-key or drop, the fields it may overwrite on a record it
+   * keeps, and the pending removals and membership deltas, which it
+   * clears whole. Bounded by the save, never by the tracker's size.
+   *
+   * `planSave` names the join-only records because they carry no
+   * statement of their own and the commit still advances them.
+   * @param {any[]} statements
+   * @param {any[]} joinOnly
+   */
+  const undoFor = (statements, joinOnly) => {
+    /** @type {Map<string, any>} */
+    const slots = new Map();
+    /** @type {Map<any, any>} */
+    const fields = new Map();
+    const takeSlot = (key) => {
+      if (!slots.has(key)) slots.set(key, records.get(key));
+    };
+    const takeFields = (record) => {
+      if (record === undefined || fields.has(record)) return;
+      fields.set(record, {
+        snapshot: record.snapshot, current: record.current,
+        stamped: record.stamped, joinOnly: record.joinOnly,
+        pendingInsert: record.pendingInsert, saved: record.saved,
+      });
+    };
+    for (const statement of statements) {
+      if (statement.kind === 'insert') {
+        for (const record of statement.records) {
+          takeSlot(record.pendingKey);
+          takeFields(record);
+        }
+      }
+      else if (statement.kind === 'update') takeFields(statement.record);
+      else if (statement.kind === 'delete') {
+        const key = keyOf(statement.removal.entity, statement.removal.parts);
+        takeSlot(key);
+        takeFields(records.get(key));
+      }
+    }
+    for (const record of joinOnly) takeFields(record);
+    return {
+      slots, fields,
+      removals: [...removals],
+      // the delta sets are mutated in place by a later link()/unlink(),
+      // so the undo needs copies rather than the live ones
+      memberships: [...memberships].map(([id, pending]) => [id, {
+        ...pending, links: new Set(pending.links), unlinks: new Set(pending.unlinks),
+      }]),
+    };
+  };
+
+  /** Put back what {@link undoFor} took a copy of: the save's statements
+   * were rolled back, so every claim they made about the database is
+   * withdrawn and a retry plans them again. */
+  const restore = (undo) => {
+    for (const [key, entry] of undo.slots) {
+      if (entry === undefined) records.delete(key);
+      else records.set(key, entry);
+    }
+    for (const [record, was] of undo.fields) {
+      record.snapshot = was.snapshot;
+      record.current = was.current;
+      record.stamped = was.stamped;
+      record.joinOnly = was.joinOnly;
+      record.pendingInsert = was.pendingInsert;
+      record.saved = was.saved;
+    }
+    removals.clear();
+    for (const [key, removal] of undo.removals) removals.set(key, removal);
+    memberships.clear();
+    for (const [id, pending] of undo.memberships) memberships.set(id, pending);
+  };
+
+  /**
+   * Advance phase: runs as soon as every statement of the save has
+   * succeeded — inside an enclosing transaction too, where the database
+   * already holds these rows and every later read, plan and optimistic
+   * guard must agree. What is registered as a settlement effect is only
+   * the WITHDRAWAL of this advance ({@link restore} over `undo`), which
+   * the owning scope runs if it rolls back.
+   *
+   * `undo` is the state the save started from. It is read for one
+   * decision: an edit made to a tracked record AFTER this save was
+   * planned is still pending work, and only a record left exactly as
+   * the save found it becomes clean.
+   * @param {any[]} statements
+   * @param {any} undo
+   */
+  const commit = (statements, undo) => {
+    const untouched = (record) => !undo.fields.has(record)
+      || undo.fields.get(record).current === record.current;
     for (const statement of statements) {
       if (statement.kind === 'insert') {
         statement.records.forEach((record, i) => {
           const plan = coreFor(statement.entity).plan;
-          let doc = record.current;
-          if (statement.returning === true) {
-            doc = deepFreeze({ ...doc, [plan.autoKey]: statement.generatedKeys[i] });
-          }
+          // the row this statement wrote is the one the save PLANNED; an
+          // edit made to the same record afterwards is not in the database
+          const planned = undo.fields.get(record)?.current ?? record.current;
+          const doc = statement.returning === true
+            ? deepFreeze({ ...planned, [plan.autoKey]: statement.generatedKeys[i] })
+            : planned;
           // re-key under the real identity
           records.delete(record.pendingKey);
           const key = recordKeyFor(statement.entity, doc);
           records.set(/** @type {string} */ (key), {
-            entity: statement.entity, snapshot: doc, current: doc, pendingInsert: false,
+            entity: statement.entity, snapshot: doc,
+            current: untouched(record) ? doc : record.current, pendingInsert: false,
           });
           record.saved = doc;
           captureRecord?.(statement.entity,
@@ -691,8 +971,9 @@ export function createTracker(context) {
         const saved = statement.newVersion === null
           ? record.stamped
           : deepFreeze({ ...record.stamped, [plan.version]: statement.newVersion });
+        const pending = untouched(record) ? null : record.current;
         record.snapshot = deepFreeze(saved);
-        record.current = record.snapshot;
+        record.current = pending ?? record.snapshot;
         record.stamped = undefined;
         captureRecord?.(statement.entity,
           plan.keys.map((k) => record.snapshot[k]), before, record.snapshot);
@@ -709,12 +990,11 @@ export function createTracker(context) {
       else if (statement.kind === 'join-insert' || statement.kind === 'join-delete') {
         for (const row of statement.joinRows ?? []) {
           // the join-row "document" lists its columns in table order
-          // (the sorted pair) so both capture modes agree exactly
-          const pair = statement.entity.split('_');
+          // (the mapping's left, right) so both capture modes agree exactly
           const value = { [row.ownColumn]: row.own, [row.targetColumn]: row.target };
           const ordered = {};
-          for (const part of pair) ordered[part + '_key'] = value[part + '_key'];
-          const keyParts = pair.map((part) => ordered[part + '_key']);
+          for (const column of statement.tableColumns) ordered[column] = value[column];
+          const keyParts = statement.tableColumns.map((column) => ordered[column]);
           if (statement.kind === 'join-insert') {
             captureRecord?.(statement.entity, keyParts, null, ordered);
           }
@@ -727,18 +1007,20 @@ export function createTracker(context) {
     // join-only records: their member state is now persisted
     for (const record of records.values()) {
       if (record.joinOnly === true) {
-        record.snapshot = record.stamped ?? record.current;
-        record.current = record.snapshot;
+        const pending = untouched(record) ? null : record.current;
+        record.snapshot = record.stamped ?? undo.fields.get(record)?.current ?? record.current;
+        record.current = pending ?? record.snapshot;
         record.joinOnly = undefined;
         record.stamped = undefined;
       }
     }
     removals.clear();
+    memberships.clear();
   };
 
   const saveChanges = () => {
     const startedAt = performance.now();
-    return chain(planSave(), ({ statements, fallbacks, unversioned }) => {
+    return chain(planSave(), ({ statements, fallbacks, joinOnly, unversioned }) => {
     const report = {
       inserted: 0, updated: 0, deleted: 0,
       joinInserted: 0, joinDeleted: 0,
@@ -754,10 +1036,22 @@ export function createTracker(context) {
       report.elapsedMs = performance.now() - startedAt;
       return report;
     }
+    // what the tracker looked like before the save, taken while it still
+    // does: the statements below run in a savepoint whose release is not
+    // a commit, so the right to KEEP what they justify waits for one
+    const undo = undoFor(statements, joinOnly);
     return chain(
       connection.transaction(() => runStatements(statements, report)),
       (finished) => {
-        commit(statements);
+        // The advance itself lands now, because inside the transaction the
+        // database DOES hold these rows: every later read, plan and
+        // optimistic guard in this unit of work has to agree with that, and
+        // a tracker still calling them pending would write them twice.
+        // What waits for the commit is the right to keep the advance — the
+        // enclosing scope withdraws it if it rolls back, which is what
+        // makes a caller's retry plan the same statements again.
+        commit(statements, undo);
+        connection.onSettle({ rollback: () => restore(undo) });
         finished.elapsedMs = performance.now() - startedAt;
         return finished;
       });
@@ -767,10 +1061,15 @@ export function createTracker(context) {
   /** Drop tracking for a key without scheduling anything. */
   const discard = (entityName, keyOrDoc) => {
     const parts = coreFor(entityName).normalizeKey(keyOrDoc);
-    records.delete(keyOf(entityName, parts));
+    const key = keyOf(entityName, parts);
+    records.delete(key);
+    // a pending membership change belongs to the key it attaches to
+    for (const id of memberships.keys()) {
+      if (id.startsWith(`${key}${UNIT_SEPARATOR}`)) memberships.delete(id);
+    }
   };
 
   return {
-    register, registerGraph, add, put, remove, discard, counts, saveChanges,
+    register, registerGraph, add, put, remove, discard, link, unlink, counts, saveChanges,
   };
 }