From 4679c89458aa5faabcea931862b9052030f35120 Mon Sep 17 00:00:00 2001
From: David Snelling <david@soulcraft.com>
Date: Mon, 3 Aug 2026 15:37:04 -0700
Subject: [PATCH] =?UTF-8?q?fix(namespace):=20noun-record=20updates=20prese?=
 =?UTF-8?q?rve=20legacy=20inline=20HNSW=20adjacency=20=E2=80=94=20the=20pl?=
 =?UTF-8?q?aceholder-adjacency=20write=20stamped=20out=20pre-codec=20recor?=
 =?UTF-8?q?ds'=20stored=20connections=20(crash-window=20unreachability);?=
 =?UTF-8?q?=20codec-era=20records=20were=20never=20at=20risk=20(empty=20fi?=
 =?UTF-8?q?eld=20is=20the=20blob=20marker);=20pin=20covers=20the=20legacy?=
 =?UTF-8?q?=20shape?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../operations/StorageOperations.ts           | 23 ++++++++-
 tests/integration/level-field-shadow.test.ts  | 47 +++++++++++++++++++
 2 files changed, 68 insertions(+), 2 deletions(-)

diff --git a/src/transaction/operations/StorageOperations.ts b/src/transaction/operations/StorageOperations.ts
index 316f1ac0..9858219b 100644
--- a/src/transaction/operations/StorageOperations.ts
+++ b/src/transaction/operations/StorageOperations.ts
@@ -77,8 +77,27 @@ export class SaveNounOperation implements Operation {
       ? null
       : await this.storage.getNoun(this.noun.id)
 
-    // Save new noun
-    await this.storage.saveNoun(this.noun)
+    // PRESERVE stored graph state on updates. Callers stage this op with
+    // placeholder adjacency ({connections: empty, level: 0}) because the
+    // vector index owns those values and persists them at flush. Codec-era
+    // records (2.4.0+) carry an empty connections field by design (adjacency
+    // lives in a separate compressed blob — the placeholder is harmless), but
+    // LEGACY pre-codec records store adjacency INLINE: writing the
+    // placeholder over one stamped out its stored connections, leaving a
+    // crash window (until the next flush) where a reload found the node
+    // unreachable. Stale adjacency in that window is tolerable — HNSW
+    // self-corrects at the reindex flush; EMPTY adjacency is silent recall
+    // loss. The read above is already paid for rollback; preservation is free.
+    const toSave: HNSWNoun =
+      previousNoun && this.noun.connections.size === 0
+        ? {
+            ...this.noun,
+            connections: previousNoun.connections || this.noun.connections,
+            level: previousNoun.level ?? this.noun.level
+          }
+        : this.noun
+
+    await this.storage.saveNoun(toSave)
 
     // Return rollback action
     return async () => {
diff --git a/tests/integration/level-field-shadow.test.ts b/tests/integration/level-field-shadow.test.ts
index d50593ff..ab5ffb9a 100644
--- a/tests/integration/level-field-shadow.test.ts
+++ b/tests/integration/level-field-shadow.test.ts
@@ -145,3 +145,50 @@ describe('level field shadow — user metadata named level is a real field', ()
     expect(EXPECTED_INDEX_EPOCH).toBe(2)
   })
 })
+
+describe('noun-record writes never stamp over stored graph state', () => {
+  let brain: Brainy
+
+  beforeEach(async () => {
+    brain = new Brainy({
+      requireSubtype: false,
+      storage: { type: 'memory' as const },
+      embeddingFunction: stubEmbedding
+    })
+    await brain.init()
+  })
+
+  afterEach(async () => {
+    await brain.close()
+  })
+
+  it('a data-changing update preserves LEGACY inline connections in the record', async () => {
+    // Codec-era records carry an EMPTY connections field by design (the
+    // adjacency lives in a separate compressed blob) — the clobber window
+    // exists only for legacy pre-codec records whose adjacency is inline.
+    // Simulate one: write the record with inline connections directly.
+    const id = await brain.add({
+      data: 'legacy-shaped node',
+      type: NounType.Concept,
+      metadata: { n: 1 }
+    })
+    const storage = (brain as any).storage
+    const rec = await storage.getNoun(id)
+    const legacy = {
+      ...rec,
+      connections: new Map([[0, new Set(['00000000-0000-4000-8000-00000000aaaa'])]]),
+      level: 1
+    }
+    await storage.saveNoun(legacy)
+    const before = await storage.getNoun(id)
+    expect(before.connections.size).toBeGreaterThan(0)
+
+    // A data-changing update stages SaveNounOperation with placeholder
+    // adjacency — the legacy inline connections must survive the write.
+    await brain.update({ id, data: 'completely re-embedded text' })
+
+    const after = await storage.getNoun(id)
+    expect(after.connections.size).toBeGreaterThan(0)
+    expect(after.level).toBe(1)
+  })
+})