feat: per-entity _rev + update({ ifRev }) CAS + add({ ifAbsent })

Optimistic concurrency for multi-writer coordination — the read-then-CAS
lock pattern + idempotent-bootstrap singleton inserts. Lands the surface the
SDK scheduler asked for in BRAINY-EXPOSE-TRANSACTIONS, scoped to what ships
cleanly without painting the 8.0 transact() API into a corner.

A. PER-ENTITY _rev FIELD

- src/coreTypes.ts — HNSWNounWithMetadata gains optional `_rev?: number`;
  STANDARD_ENTITY_FIELDS includes it so resolveEntityField routes correctly.
- src/types/brainy.types.ts — Entity<T> gains optional `_rev?: number`;
  Result<T> mirrors it on the convenience flatten layer.
- src/brainy.ts add() — initializes `_rev: 1` in storageMetadata. New entities
  always start at 1.
- src/brainy.ts update() — reads currentRev off the persisted metadata
  (falls back to 1 for pre-7.31.0 entities with no _rev), writes
  `_rev: currentRev + 1` into the updated metadata. Every successful update()
  bumps by exactly 1.
- src/brainy.ts convertNounToEntity + convertMetadataToEntity — both pull
  _rev out of the storage metadata and surface it at the top level of Entity.
  Pre-7.31.0 entities (no _rev in storage) read as `_rev: 1` so consumers
  see a consistent value.
- src/storage/baseStorage.ts — six destructure sites updated to pull _rev
  out of the metadata bag so it doesn't leak into customMetadata. Noun-side
  returns surface _rev; verb-side destructures correctly but doesn't expose
  it on HNSWVerbWithMetadata (verb CAS is future work).
- src/brainy.ts createResult() — flattens entity._rev onto the Result for
  backward compat with the existing convenience-field layer.

B. update({ ifRev }) OPTIMISTIC CONCURRENCY

- src/types/brainy.types.ts — UpdateParams<T> gains optional `ifRev?: number`.
- src/transaction/RevisionConflictError.ts (NEW) — carries `{ id, expected,
  actual }`. Message names the recipe: refetch with brain.get() and retry
  with the latest _rev. Subclass of Error.
- src/brainy.ts update() — when params.ifRev is provided, compares against
  currentRev (the rev we just read) and throws RevisionConflictError on
  mismatch before any storage write. Omitting ifRev keeps the prior
  unconditional-update behavior; existing consumers see no change.
- src/transaction/index.ts — exports RevisionConflictError.
- src/index.ts — public export of RevisionConflictError.

C. add({ ifAbsent }) BY-ID IDEMPOTENT INSERT

- src/types/brainy.types.ts — AddParams<T> gains optional `ifAbsent?: boolean`;
  AddManyParams<T> mirrors it as a batch-level flag.
- src/brainy.ts add() — when params.id AND params.ifAbsent, pre-reads
  storage.getNounMetadata(id); if present, returns the existing id without
  writing. No throw, no overwrite. Ignored when id is omitted (a fresh UUID
  can never collide).
- src/brainy.ts addMany() — propagates the batch-level ifAbsent to each
  item's add() call. Per-item ifAbsent takes precedence so callers can
  override individual rows.

WHAT'S NOT SHIPPED (and why)

A public brain.transaction(fn) wrapper was on the table but was cut. The
internal TransactionManager exposes raw Operation classes (SaveNounMetadata,
etc.) that take StorageAdapter as a constructor argument. A clean high-level
facade in 7.31.0 would have meant either:

  (a) Delegate to brain.add() / update() / relate(). Each of those opens its
      own internal transaction and commits before the closure returns. Looks
      atomic, isn't — a footgun.
  (b) Thread an optional `tx?` through every internal write site in
      brainy.ts (8 transactionManager.executeTransaction sites). ~2 days of
      real refactor with regression surface, and the API shape changes again
      in 8.0 anyway.

The SDK scheduler's actual ask (BRAINY-EXPOSE-TRANSACTIONS) is the
read-then-CAS lock pattern. _rev + ifRev solves it completely. Multi-write
atomicity is the 8.0 brain.transact() use case where the Datomic-style
immutable Db makes it atomic by construction — that's the right home.

TESTS

- New tests/integration/rev-and-ifabsent.test.ts (18 tests):
  - _rev initialization (1 on add) and surface on get fast/full paths + find
  - _rev auto-bump on update across multiple writes
  - update({ ifRev }) pass / fail / message format / omitted / legacy-no-rev
  - add({ ifAbsent }) writes when absent / no-op when present / id-required
  - addMany({ ifAbsent }) propagation + per-item override
  - SDK-scheduler scenario: two concurrent CAS updates, one wins one throws
- Unit suite unchanged: 1468/1468.
- All integration subtype + verb + strict + find-limits + new rev suites
  pass: 96/96.

DOCS

- New docs/guides/optimistic-concurrency.md (public: true) — full reference:
  the lock pattern, read-modify-write retry, idempotent bootstrap, how _rev
  interacts with brain.versions, branches/fork, and VFS, what's coming in 8.0.
- docs/api/README.md — add() and update() entries get the new params + tips
  pointing at the new guide.
- RELEASES.md v7.31.0 entry.

CORTEX COMPATIBILITY

Zero changes required. _rev is a metadata column already supported by
NativeColumnStore. The auto-bump runs in Brainy JS before any storage call;
Cortex never sees the per-entity counter.

8.0 FORWARD-COMPAT

_rev, ifRev, RevisionConflictError, and ifAbsent survive the 8.0 Db redesign
unchanged. 8.0 layers brain.transact(tx, { ifAtGeneration }) for whole-tx CAS
on top of the same per-entity mechanism — per-entity for single-record
patterns (job locks, idempotent state machines), generation-based for
"did the world move under me." Locked in .strategy/BRAINY-8.0-SUBTYPE-CONTRACT.md § C-6.

Verification

- npx tsc --noEmit: clean
- npm test: 1468 / 1468 unit
- All integration suites including new rev-and-ifabsent: 96/96
- npm run build: clean
- Closed-source product reference audit: clean

src/types/brainy.types.ts

@@ -49,6 +49,13 @@ export interface Entity<T = any> {
   confidence?: number
   /** Entity importance/salience (0-1) */
   weight?: number
+  /**
+   * Monotonic revision counter, auto-bumped on every successful `update()`.
+   * Starts at `1` on `add()`. Pre-7.31.0 entities without `_rev` are read as `1`.
+   * Pass back as `update({ id, ..., ifRev: _rev })` for optimistic-concurrency CAS —
+   * throws `RevisionConflictError` if the persisted rev moved since read.
+   */
+  _rev?: number
 }
 
 /**
@@ -126,6 +133,7 @@ export interface Result<T = any> {
   data?: any           // Entity data (from entity.data)
   confidence?: number  // Type classification confidence (from entity.confidence)
   weight?: number      // Entity importance (from entity.weight)
+  _rev?: number        // Monotonic revision counter (from entity._rev) — pass back as update({ ifRev }) for CAS
 
   // Full entity (preserved for backward compatibility)
   entity: Entity<T>
@@ -197,6 +205,13 @@ export interface AddParams<T = any> {
   weight?: number
   /** Track which augmentation created this entity */
   createdBy?: { augmentation: string; version: string }
+  /**
+   * Conditional insert. When `true` AND a custom `id` is supplied AND an entity with
+   * that `id` already exists, `add()` returns the existing `id` without writing — no
+   * throw, no overwrite. Used for idempotent bootstrap and create-or-noop patterns.
+   * Ignored when `id` is omitted (a freshly generated UUID can never collide).
+   */
+  ifAbsent?: boolean
 }
 
 /**
@@ -212,6 +227,13 @@ export interface UpdateParams<T = any> {
   vector?: Vector             // New pre-computed vector
   confidence?: number          // Update type classification confidence
   weight?: number              // Update entity importance/salience
+  /**
+   * Optimistic concurrency check. When provided, the update fails with
+   * `RevisionConflictError` if the persisted entity's `_rev` does not equal `ifRev`.
+   * `_rev` is auto-bumped on every successful update — read it from the entity returned
+   * by `get()` / `find()` / `search()`. Omit to skip the check (unconditional update).
+   */
+  ifRev?: number
 }
 
 /**
@@ -499,6 +521,11 @@ export interface AddManyParams<T = any> {
   chunkSize?: number        // Batch size (default: 100)
   onProgress?: (done: number, total: number) => void
   continueOnError?: boolean  // Continue if some fail
+  /**
+   * Conditional insert applied to every item. Equivalent to setting `ifAbsent: true`
+   * on each item individually. Item-level `ifAbsent` overrides the batch flag.
+   */
+  ifAbsent?: boolean
 }
 
 /**