feat(8.0): upsert + FindParams.includeVectors + removeMany adaptive chunking

Three additive ergonomics from the API-simplification audit (no behavior change
to existing call sites):

- AddParams.upsert: create-or-update in one call. With a custom id, an existing
  entity is MERGED via the update path (merges metadata, re-embeds changed data,
  bumps _rev, PRESERVES createdAt) instead of the destructive full overwrite a
  plain add() does. Mutually exclusive with ifAbsent (throws if both set);
  ignored when no id is supplied. Wired into add(), addMany (per-item flag
  propagation), and the transact add op (routes to planTxUpdate). Kills the
  get()-then-add() round-trip for idempotent writes.
- FindParams.includeVectors: mirror of GetOptions.includeVectors — find() returns
  stored vectors when set; default stays empty (the perf contract is preserved).
  Honored on both the query and metadata-only where paths, and in db.find().
- removeMany adaptive chunking: replaced the hardcoded chunkSize=10 with
  params.chunkSize ?? storageConfig.maxBatchSize, matching addMany/relateMany —
  one storage-adaptive batch policy across all *Many methods (no thrash on
  high-latency backends).

Tests: tests/unit/brainy/upsert.test.ts (insert/merge/createdAt-preserved/
re-embed/ifAbsent-conflict/no-id/addMany/transact), find-include-vectors.test.ts
(true/default/where-path), batch-operations.test.ts (removeMany >10 items).

src/types/brainy.types.ts

@@ -346,6 +346,24 @@ export interface AddParams<T = any> {
    * Ignored when `id` is omitted (a freshly generated UUID can never collide).
    */
   ifAbsent?: boolean
+  /**
+   * Create-or-update in a single call. When `true` AND a custom `id` is supplied AND
+   * an entity with that `id` already exists, `add()` applies the supplied fields as an
+   * UPDATE instead of the default destructive overwrite: metadata is MERGED (not
+   * replaced), `data` re-embeds only when it changed, `_rev` is bumped, and the
+   * original `createdAt` is PRESERVED. When no entity with that `id` exists, `add()`
+   * inserts normally (a fresh `_rev` of 1). Ignored — behaves as a plain insert — when
+   * `id` is omitted, since a freshly generated UUID can never collide.
+   *
+   * Mutually exclusive with {@link AddParams.ifAbsent}: `ifAbsent` SKIPS an existing
+   * entity, `upsert` MERGES into it — supplying both throws.
+   *
+   * @example
+   * // First call inserts; a later call with the same id merges + bumps _rev.
+   * await brain.add({ id: 'customer-42', type: 'customer', data: 'Acme', upsert: true })
+   * await brain.add({ id: 'customer-42', type: 'customer', metadata: { tier: 'gold' }, upsert: true })
+   */
+  upsert?: boolean
 }
 
 /**
@@ -538,6 +556,14 @@ export interface FindParams<T = any> {
   includeRelations?: boolean // Include entity relationships
   excludeVFS?: boolean       // Exclude VFS entities from results (default: false - VFS included)
   service?: string           // Multi-tenancy filter
+  /**
+   * Return each result's stored embedding under `entity.vector`. Defaults to `false`,
+   * in which case `entity.vector` is an empty array (the perf default — vectors are
+   * large and most reads don't need them). Set `true` to get the persisted vector
+   * back from `find()` without a recompute, e.g. to feed downstream similarity math.
+   * Mirrors {@link GetOptions.includeVectors} on `get()`.
+   */
+  includeVectors?: boolean
 
   // Hybrid search options
   searchMode?: 'auto' | 'text' | 'semantic' | 'vector' | 'hybrid'  // Search strategy: auto (default), text-only, semantic/vector-only, or explicit hybrid
@@ -738,6 +764,14 @@ export interface AddManyParams<T = any> {
    * on each item individually. Item-level `ifAbsent` overrides the batch flag.
    */
   ifAbsent?: boolean
+  /**
+   * Create-or-update applied to every item. Equivalent to setting `upsert: true` on
+   * each item individually (see {@link AddParams.upsert}): an item whose custom `id`
+   * already exists is MERGED as an update rather than overwritten. Item-level `upsert`
+   * overrides the batch flag. Mutually exclusive with {@link AddManyParams.ifAbsent}
+   * at the item level — an item resolving to both throws.
+   */
+  upsert?: boolean
 }
 
 /**
@@ -759,6 +793,14 @@ export interface RemoveManyParams {
   type?: NounType           // Remove all of type
   where?: any               // Remove by metadata
   limit?: number            // Max to remove (safety)
+  /**
+   * Entities removed per transaction chunk. Each chunk is one atomic transaction —
+   * a chunk commits or rolls back together, and failures are isolated to their chunk.
+   * Defaults to the storage adapter's `maxBatchSize` (memory: 1000, S3/R2: 100,
+   * GCS: 50), so zero-config removals match the adapter's characteristics. Override
+   * only to tune throughput vs. transaction granularity.
+   */
+  chunkSize?: number
   onProgress?: (done: number, total: number) => void
   continueOnError?: boolean  // Continue processing if a removal fails
 }