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

@ -646,9 +646,20 @@ export class GraphAdjacencyIndex implements GraphIndexProvider {
* @param verb - The verb to index (endpoint UUIDs are authoritative).
* @param sourceInt - The source entity's interned int (contract parity).
* @param targetInt - The target entity's interned int (contract parity).
* @param generation - The commit generation (contract parity). The JS index
* keeps a single live adjacency view, not a per-generation edge chain, so
* it ignores this: `db.asOf(g)` graph hops on the open-core path see edges
* as-of-now (the one documented graph time-travel limitation native
* providers thread this into a versioned endpoint store for correctness).
* @returns The interned verb int for `verb.id` (stable for the index lifetime).
*/
async addVerb(verb: GraphVerb, sourceInt: bigint, targetInt: bigint): Promise<bigint> {
async addVerb(
verb: GraphVerb,
sourceInt: bigint,
targetInt: bigint,
generation: bigint
): Promise<bigint> {
void generation // Contract parity — no per-generation chain in the JS index.
await this.ensureInitialized()
return BigInt(await this.indexVerb(verb))
}
@ -703,9 +714,13 @@ export class GraphAdjacencyIndex implements GraphIndexProvider {
* retained so previously returned verb ints stay resolvable via
* {@link verbIntsToIds}.
* @param verbId - The verb's UUID string.
* @param generation - The commit generation (contract parity). The JS index
* tombstones immediately rather than chaining the removal per generation,
* so it ignores this (see {@link addVerb} for the time-travel rationale).
* @returns Resolves once the verb no longer appears in reads.
*/
async removeVerb(verbId: string): Promise<void> {
async removeVerb(verbId: string, generation: bigint): Promise<void> {
void generation // Contract parity — no per-generation chain in the JS index.
await this.ensureInitialized()
// Load verb from cache/storage to get type info