feat(8.0): thread commit generation through the graph-write provider contract

Graph time-travel needs an edge's existence recorded per generation so
db.asOf(g) hops resolve historically correct endpoints. The metadata layer
already threads brainy's commit generation per write; the graph write path did
not, leaving a versioned verb-endpoint store unable to answer "which edges
existed at generation g".

- GraphIndexProvider.addVerb/removeVerb gain a `generation: bigint` parameter
  (the same watermark the storage layer stamps onto the record). A provider with
  a per-generation edge chain stamps the edge at that generation; the JS baseline
  has no such chain and accepts-and-ignores it — graph time-travel is a
  native-provider capability, and the open-core path serves edges as-of-now (the
  one documented graph time-travel limitation).
- The two graph transaction operations resolve the generation via a thunk at
  EXECUTE time: the generation store assigns the batch generation only once the
  commit begins executing, after the operations are planned. The same generation
  is reused for an operation's rollback half.
- All graph-write call sites pass the in-flight generation.

Adds a spy-provider test proving the threading, execute-time resolution, and
forward/rollback generation reuse. The JS index ignores the value, so behaviour
is unchanged: unit 1402/1402, db-mvcc 25/25, bigint-contract relate/unrelate 10/10.
This commit is contained in:
David Snelling 2026-06-16 09:41:59 -07:00
parent b26d3d42b3
commit 0951fa1da0
6 changed files with 195 additions and 26 deletions

View file

@ -231,16 +231,26 @@ export interface GraphIndexProvider {
* @param verb - The verb to index (endpoint UUIDs + derived `sourceInt`/`targetInt`).
* @param sourceInt - The source entity's interned int.
* @param targetInt - The target entity's interned int.
* @param generation - Brainy's commit generation for this write the same
* watermark the storage layer stamps onto the record. A provider with a
* per-generation edge chain records the edge's existence at this generation
* so `db.asOf(g)` graph hops resolve historically correct endpoints; the
* JS baseline has no such chain and ignores it (graph time-travel is a
* native-provider capability see the consistency-model doc).
* @returns The interned verb int for `verb.id` (feeds Brainy's warm cache).
*/
addVerb(verb: GraphVerb, sourceInt: bigint, targetInt: bigint): Promise<bigint>
addVerb(verb: GraphVerb, sourceInt: bigint, targetInt: bigint, generation: bigint): Promise<bigint>
/**
* @description Remove one verb from the index by its id string. The verb's
* interned int stays reserved (ints are never recycled within a generation).
* @param verbId - The verb's UUID string.
* @param generation - Brainy's commit generation for this removal. A provider
* with a per-generation edge chain tombstones the edge at this generation
* (so it remains visible to `db.asOf(g)` for `g` before the removal); the
* JS baseline removes immediately and ignores it.
* @returns Resolves once the verb no longer appears in reads.
*/
removeVerb(verbId: string): Promise<void>
removeVerb(verbId: string, generation: bigint): Promise<void>
rebuild(): Promise<void>
flush(): Promise<void>