fix(transact): metadata-index ops take their JSON-safe view at the crossing, not at construction

transact()'s delete legs (direct unrelate and the noun-remove cascade) hand
the SAME verb object to the graph-retraction op and the metadata-retraction
op. The metadata leg sanitized at PLAN time, when the verb was still clean,
so the wrap returned the same reference — then the graph op's execute-time
endpoint resolution (deliberately deferred for same-batch forward refs)
mirrored BigInt sourceInt/targetInt onto the shared object, and the metadata
op crossed the seam with them. A strict provider rightly refuses that
crossing, so every transact-wrapped edge delete aborted; direct unrelate()
resolves ints at build time, before its sanitize, which is why no existing
gate saw it.

The JSON-safe view now lives in a shared leaf (utils/jsonSafeIndexMetadata)
and is applied INSIDE AddToMetadataIndexOperation and
RemoveFromMetadataIndexOperation at execute and rollback time — the one
place no plan-vs-execute ordering can bypass. Pins: the fleet repro, the
cascade shape, a mixed batch, and unit pins that mutate the entity after
construction against a strict seam (5 red before, 5 green after).

src/brainy.ts

@@ -15,6 +15,7 @@ import { JsHnswVectorIndex } from './hnsw/hnswIndex.js'
 import { createStorage, resolveFilesystemRoot } from './storage/storageFactory.js'
 import type { StorageOptions } from './storage/storageFactory.js'
 import { rebuildCounts } from './utils/rebuildCounts.js'
+import { jsonSafeIndexMetadata } from './utils/jsonSafeIndexMetadata.js'
 import type { MetadataWriteBuffer } from './utils/metadataWriteBuffer.js'
 import { BaseStorage } from './storage/baseStorage.js'
 import {
@@ -4203,32 +4204,19 @@ export class Brainy<T = any> implements BrainyInterface<T> {
    */
   /**
    * @description A JSON-safe view of a record bound for the metadata-index
-   * crossing. The seam's metadata is JSON-safe BY CONTRACT (a native provider
-   * serializes it; u64 ints as Number corrupt above 2^53) — but
-   * {@link resolveVerbEndpointInts} MIRRORS the resolved endpoint ints onto
-   * the verb object itself as BigInt (`verb.sourceInt`/`targetInt`), so a
-   * verb object reused as index metadata carried BigInts into
-   * JSON.stringify, which throws, aborting the whole transaction (found by
-   * the first joint pair gate). Endpoint ints ride their OWN op params on the
-   * graph legs — the metadata crossing drops every BigInt-valued top-level
-   * key instead of guessing at a lossy numeric encoding.
+   * crossing — delegates to the shared {@link jsonSafeIndexMetadata} leaf,
+   * which the metadata-index transaction operations ALSO apply at execute
+   * and rollback time. This plan-time wrap alone proved insufficient: it
+   * returns the same reference when the record is clean, and `transact()`'s
+   * delete legs share that reference with a graph-retraction op whose
+   * execute-time endpoint resolution mirrors BigInt ints onto it (the full
+   * aliasing story lives on the leaf module's doc).
    * @param metadata - The candidate index-metadata record.
    * @returns The same object when already JSON-safe, else a shallow copy
    *   without the BigInt-valued keys.
    */
   private static jsonSafeIndexMetadata(metadata: unknown): unknown {
-    if (metadata === null || typeof metadata !== 'object') return metadata
-    const rec = metadata as Record<string, unknown>
-    let hasBigint = false
-    for (const k in rec) {
-      if (typeof rec[k] === 'bigint') { hasBigint = true; break }
-    }
-    if (!hasBigint) return metadata
-    const out: Record<string, unknown> = {}
-    for (const k in rec) {
-      if (typeof rec[k] !== 'bigint') out[k] = rec[k]
-    }
-    return out
+    return jsonSafeIndexMetadata(metadata)
   }
 
   private metadataIndexRetractionOp(

src/transaction/operations/IndexOperations.ts

@@ -14,6 +14,7 @@ import type { MetadataIndexManager } from '../../utils/metadataIndex.js'
 import type { GraphVerb } from '../../coreTypes.js'
 import type { Operation, RollbackAction } from '../types.js'
 import { isZeroNormVector } from '../../utils/distance.js'
+import { jsonSafeIndexMetadata } from '../../utils/jsonSafeIndexMetadata.js'
 import { prodLog } from '../../utils/logger.js'
 
 /**
@@ -390,13 +391,21 @@ export class AddToMetadataIndexOperation implements Operation {
     // rollback so add + undo reference the same watermark.
     const generation = this.generationFn?.()
 
-    // Add to metadata index (skipFlush=true for transaction atomicity)
-    await this.index.addToIndex(this.id, this.entity, true, false, generation)
+    // The JSON-safe view is taken HERE, per crossing, never at construction:
+    // the entity reference this op holds can be mutated between plan and
+    // execute (a graph op's execute-time endpoint-int resolution mirrors
+    // BigInts onto a shared verb object) — see jsonSafeIndexMetadata's
+    // module doc.
+    await this.index.addToIndex(
+      this.id, jsonSafeIndexMetadata(this.entity), true, false, generation
+    )
 
     // Return rollback action
     return async () => {
       // Remove from metadata index
-      await this.index.removeFromIndex(this.id, this.entity, generation)
+      await this.index.removeFromIndex(
+        this.id, jsonSafeIndexMetadata(this.entity), generation
+      )
     }
   }
 }
@@ -432,13 +441,21 @@ export class RemoveFromMetadataIndexOperation implements Operation {
     // Resolve the removal generation once; reuse it for the rollback re-add.
     const generation = this.generationFn?.()
 
-    // Remove from metadata index
-    await this.index.removeFromIndex(this.id, this.entity, generation)
+    // Sanitized per crossing, never at construction — transact()'s delete
+    // legs hand this op the SAME verb object the graph-retraction op's
+    // execute-time endpoint resolution mutates (BigInt sourceInt/targetInt),
+    // so a plan-time view aliases the pollution. See jsonSafeIndexMetadata's
+    // module doc.
+    await this.index.removeFromIndex(
+      this.id, jsonSafeIndexMetadata(this.entity), generation
+    )
 
     // Return rollback action
     return async () => {
       // Re-add with original metadata (skipFlush=true)
-      await this.index.addToIndex(this.id, this.entity, true, false, generation)
+      await this.index.addToIndex(
+        this.id, jsonSafeIndexMetadata(this.entity), true, false, generation
+      )
     }
   }
 }

src/utils/jsonSafeIndexMetadata.ts

@@ -0,0 +1,47 @@
+/**
+ * @module utils/jsonSafeIndexMetadata
+ * @description The metadata-index crossing's JSON-safety law, as a leaf
+ * function both the coordinator and the transaction operations share.
+ *
+ * The seam's metadata is JSON-safe BY CONTRACT (a native provider serializes
+ * it; u64 ints as Number corrupt above 2^53) — but `resolveVerbEndpointInts`
+ * MIRRORS the resolved endpoint ints onto the verb object itself as BigInt
+ * (`verb.sourceInt`/`targetInt`), so a verb object reused as index metadata
+ * carries BigInts into JSON.stringify, which throws, aborting the whole
+ * transaction. Endpoint ints ride their OWN op params on the graph legs — the
+ * metadata crossing drops every BigInt-valued top-level key instead of
+ * guessing at a lossy numeric encoding.
+ *
+ * WHY THIS IS A LEAF MODULE, ENFORCED AT THE CROSSING: sanitizing only at
+ * operation-construction time is not enough. `transact()`'s delete legs pass
+ * the SAME verb object to both the graph-retraction op (whose endpoint-int
+ * thunk deliberately resolves at EXECUTE time, for same-batch forward refs)
+ * and the metadata-retraction op. At plan time the verb is still clean, so a
+ * plan-time sanitize returns the same reference — then the graph op executes
+ * first, mirrors the BigInt ints onto the shared object, and the metadata op
+ * crosses the seam with them (found by the first fleet adoption of the native
+ * pair: every transact-wrapped edge delete aborted). The crossing itself is
+ * the only place ordering cannot bypass.
+ */
+
+/**
+ * A JSON-safe view of a record bound for the metadata-index crossing.
+ *
+ * @param metadata - The candidate index-metadata record.
+ * @returns The same object when already JSON-safe, else a shallow copy
+ *   without the BigInt-valued keys.
+ */
+export function jsonSafeIndexMetadata(metadata: unknown): unknown {
+  if (metadata === null || typeof metadata !== 'object') return metadata
+  const rec = metadata as Record<string, unknown>
+  let hasBigint = false
+  for (const k in rec) {
+    if (typeof rec[k] === 'bigint') { hasBigint = true; break }
+  }
+  if (!hasBigint) return metadata
+  const out: Record<string, unknown> = {}
+  for (const k in rec) {
+    if (typeof rec[k] !== 'bigint') out[k] = rec[k]
+  }
+  return out
+}