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/types/brainy.types.ts

@@ -6,6 +6,12 @@
 
 import { StorageAdapter, Vector } from '../coreTypes.js'
 import { NounType, VerbType } from './graphTypes.js'
+import type {
+  EntityMetadataInput,
+  EntityMetadataPatch,
+  RelationMetadataInput,
+  RelationMetadataPatch
+} from './reservedFields.js'
 
 // ============= Core Types =============
 
@@ -283,8 +289,18 @@ export interface AddParams<T = any> {
    * aggregation on the standard-field fast path.
    */
   subtype?: string
-  /** Structured queryable fields — indexed by MetadataIndex, used in `where` filters */
-  metadata?: T
+  /**
+   * Structured queryable fields — indexed by MetadataIndex, used in `where` filters.
+   *
+   * Reserved entity fields (`RESERVED_ENTITY_FIELDS` — `noun`, `subtype`, `createdAt`,
+   * `updatedAt`, `confidence`, `weight`, `service`, `data`, `createdBy`, `_rev`) may NOT
+   * appear here — they have dedicated top-level params and the type makes a literal
+   * reserved key a compile error. Untyped (JavaScript) callers that pass one anyway are
+   * normalized at write time: user-settable fields remap to their top-level param
+   * (top-level wins when both are supplied), system-managed fields are dropped with a
+   * one-shot warning.
+   */
+  metadata?: EntityMetadataInput<T>
   /** Custom entity ID (auto-generated UUID v4 if not provided) */
   id?: string
   /** Pre-computed embedding vector (skips auto-embedding when provided) */
@@ -314,7 +330,15 @@ export interface UpdateParams<T = any> {
   data?: any                   // New content to re-embed
   type?: NounType             // Change type
   subtype?: string            // Change subtype (set to '' or null-equivalent via dedicated unset is future work)
-  metadata?: Partial<T>        // Metadata to update
+  /**
+   * Metadata fields to merge (or replace when `merge: false`). Reserved entity
+   * fields (`RESERVED_ENTITY_FIELDS`) may NOT appear here — `confidence` /
+   * `weight` / `subtype` have dedicated params on this call, and the rest are
+   * system-managed. A literal reserved key is a compile error; untyped callers
+   * are normalized at write time (remap user-settable, drop system-managed
+   * with a one-shot warning).
+   */
+  metadata?: EntityMetadataPatch<T>
   merge?: boolean             // Merge or replace metadata (default: true)
   vector?: Vector             // New pre-computed vector
   confidence?: number          // Update type classification confidence
@@ -355,8 +379,14 @@ export interface RelateParams<T = any> {
   weight?: number
   /** Content for the relationship (optional — overrides auto-computed vector) */
   data?: any
-  /** Structured queryable fields on the edge */
-  metadata?: T
+  /**
+   * Structured queryable fields on the edge. Reserved relationship fields
+   * (`RESERVED_RELATION_FIELDS` — `verb`, `subtype`, `createdAt`, `updatedAt`,
+   * `confidence`, `weight`, `service`, `data`, `createdBy`, `_rev`) may NOT
+   * appear here — they have dedicated params. A literal reserved key is a
+   * compile error; untyped callers are normalized at write time.
+   */
+  metadata?: RelationMetadataInput<T>
   /** Create reverse edge too (default: false) */
   bidirectional?: boolean
   /** Multi-tenancy service identifier */
@@ -377,7 +407,13 @@ export interface UpdateRelationParams<T = any> {
   weight?: number            // New weight
   confidence?: number        // New confidence (0-1)
   data?: any                 // New content
-  metadata?: Partial<T>      // Metadata to update
+  /**
+   * Metadata fields to merge (or replace when `merge: false`). Reserved
+   * relationship fields (`RESERVED_RELATION_FIELDS`) may NOT appear here —
+   * a literal reserved key is a compile error; untyped callers are
+   * normalized at write time.
+   */
+  metadata?: RelationMetadataPatch<T>
   merge?: boolean            // Merge or replace metadata
 }