feat(8.0): reserved-field contract — one canonical location, typed prevention, unified read/write

Brainy-owned field names (noun/verb, subtype, createdAt, updatedAt,
confidence, weight, service, data, createdBy, _rev) now have exactly one
home — top level — enforced by three layers driven from a single source of
truth, src/types/reservedFields.ts (RESERVED_ENTITY_FIELDS /
RESERVED_RELATION_FIELDS, exported):

1. Compile time — AddParams/UpdateParams/RelateParams/UpdateRelationParams
   metadata (and the transact() ops that extend them) reject a literal
   reserved key as a TypeScript error while keeping generic T ergonomics
   (typed bags, untyped brains, index-signature shapes, and a documented
   exemption for T-declared reserved keys). Pinned by @ts-expect-error
   type tests run under vitest typecheck mode on every unit run.

2. Write time — the 7.x update() remap is ported to 8.0 and extended to
   every write path: add/update/relate/updateRelation, their transact()
   mirrors, and db.with() overlays. User-settable fields lift to their
   dedicated param (top-level wins when both are supplied — closes the 7.x
   trap where update({metadata:{confidence}}) silently no-oped), and
   system-managed fields drop with a one-shot warning naming the right
   path. A remapped subtype satisfies subtype-pairing enforcement exactly
   like a top-level one.

3. Read time — every storage combine goes through one canonical hydration
   helper (hydrateNounWithMetadata / hydrateVerbWithMetadata over
   splitNoun/VerbMetadataRecord), so reserved fields surface ONLY top-level
   and entity/relation.metadata carry ONLY custom fields on live reads,
   batch reads, paginated listings, getRelations by source/target, streamed
   verbs, and historical asOf() materialization alike.

Read-path echoes found and fixed (previously the full stored record —
including the verb type key — leaked inside metadata): noun pagination,
verb pagination, getVerbsBySource/ByTarget (adjacency + shard fallback),
getVerbsBySourceBatch (which also dropped subtype/data), and the
filesystem verb stream. getRelations() results now surface
confidence/updatedAt top-level via verbsToRelations, updateRelation() no
longer erases service/createdBy, relate() persists its top-level
confidence/service params, and the dead convertHNSWVerbToGraphVerb echo
path is deleted. Import paths (CLI extract, deduplicator, coordinators,
neural import) write confidence through the dedicated param instead of the
bag. UpdateRelationParams is now exported from the package root.

Documented for consumers in docs/concepts/consistency-model.md ("Reserved
fields") and RELEASES.md. Regression tests ported from the 7.x fix and
extended to the full 8.0 contract (17 runtime tests + 41 type-level
assertions); full unit suite 1427/1427, db-mvcc integration 24/24.

src/import/EntityDeduplicator.ts

@@ -155,7 +155,15 @@ export class EntityDeduplicator {
         throw new Error(`Entity ${existingId} not found`)
       }
 
-      // Merge metadata
+      // Update confidence (weighted average) — `confidence` is a reserved
+      // top-level field, so it travels via the dedicated update() param, not
+      // the metadata bag.
+      const mergedConfidence = this.mergeConfidence(
+        existing.confidence ?? 0.5,
+        candidate.confidence
+      )
+
+      // Merge metadata (custom fields only — reserved fields are top-level)
       const mergedMetadata = {
         ...existing.metadata,
         // Track provenance
@@ -168,11 +176,6 @@ export class EntityDeduplicator {
           ...(existing.metadata?.vfsPaths || [existing.metadata?.vfsPath]).filter(Boolean),
           candidate.metadata?.vfsPath
         ].filter(Boolean),
-        // Update confidence (weighted average)
-        confidence: this.mergeConfidence(
-          existing.metadata?.confidence || 0.5,
-          candidate.confidence
-        ),
         // Merge other metadata
         ...this.mergeMetadataFields(existing.metadata, candidate.metadata),
         // Track last update
@@ -183,6 +186,7 @@ export class EntityDeduplicator {
       // Update entity
       await this.brain.update({
         id: existingId,
+        confidence: mergedConfidence,
         metadata: mergedMetadata,
         merge: true
       })
@@ -191,7 +195,7 @@ export class EntityDeduplicator {
         mergedEntityId: existingId,
         wasMerged: true,
         mergedWith: existing.metadata?.name || existingId,
-        confidence: mergedMetadata.confidence,
+        confidence: mergedConfidence,
         provenance: mergedMetadata.imports
       }
     } catch (error) {
@@ -218,17 +222,18 @@ export class EntityDeduplicator {
     // No duplicate found, create new entity. Preserve any subtype the candidate
     // carried (set by the extractor or upstream importer), else fall back to
     // `'imported'` so enforcement doesn't fire (added 7.30.1).
+    // `confidence` is a reserved top-level field (dedicated add() param);
+    // creation time is system-managed — neither belongs in the metadata bag.
     const entityId = await this.brain.add({
       data: candidate.description || candidate.name,
       type: candidate.type,
       subtype: (candidate as any).subtype ?? 'imported',
+      confidence: candidate.confidence,
       metadata: {
         ...candidate.metadata,
         name: candidate.name,
-        confidence: candidate.confidence,
         imports: [importSource],
         vfsPaths: [candidate.metadata?.vfsPath].filter(Boolean),
-        createdAt: Date.now(),
         mergeCount: 0
       }
     })