@livestore/common 0.0.58-dev.5 → 0.0.58-dev.7

package/src/sync/next/rebase-events.ts

@@ -0,0 +1,97 @@
+import type { EventId } from '../../adapter-types.js'
+import type { MutationDef, MutationEvent, MutationEventFactsSnapshot } from '../../schema/mutations.js'
+import {
+  applyFactGroups,
+  factsIntersect,
+  type FactValidationResult,
+  getFactsGroupForMutationArgs,
+  validateFacts,
+} from './facts.js'
+import type { HistoryDagNode } from './history-dag.js'
+
+export type RebaseEventWithConflict = HistoryDagNode & {
+  conflictType: 'overlap' | 'missing-requirement'
+  conflictingEvents: HistoryDagNode[]
+}
+
+export type RebaseInput = {
+  newRemoteEvents: RebaseEventWithConflict[]
+  pendingLocalEvents: RebaseEventWithConflict[]
+  validate: (args: {
+    rebasedLocalEvents: MutationEvent.PartialAny[]
+    mutationDefs: Record<string, MutationDef.Any>
+  }) => FactValidationResult
+}
+
+export type RebaseOutput = {
+  rebasedLocalEvents: MutationEvent.PartialAny[]
+}
+
+export type RebaseFn = (input: RebaseInput) => RebaseOutput
+
+export const defaultRebaseFn: RebaseFn = ({ pendingLocalEvents }) => {
+  if (pendingLocalEvents.some((_) => _.conflictType === 'missing-requirement')) {
+    throw new Error('missing-requirement conflicts must be resolved before rebasing')
+  }
+
+  return { rebasedLocalEvents: pendingLocalEvents }
+}
+
+export const rebaseEvents = ({
+  rebaseFn,
+  pendingLocalEvents,
+  newRemoteEvents,
+  currentFactsSnapshot,
+}: {
+  pendingLocalEvents: HistoryDagNode[]
+  newRemoteEvents: HistoryDagNode[]
+  rebaseFn: RebaseFn
+  currentFactsSnapshot: MutationEventFactsSnapshot
+}): MutationEvent.Any[] => {
+  const initialSnapshot = new Map(currentFactsSnapshot)
+  applyFactGroups(
+    newRemoteEvents.map((event) => event.factsGroup),
+    initialSnapshot,
+  )
+
+  // TODO detect and set actual conflict type (overlap or missing-requirement)
+  // TODO bring back validateFacts
+  const { rebasedLocalEvents } = rebaseFn({
+    pendingLocalEvents: pendingLocalEvents.map((pending) => ({
+      ...pending,
+      conflictType: 'overlap',
+      conflictingEvents: newRemoteEvents.filter((remote) =>
+        factsIntersect(remote.factsGroup.modifySet, pending.factsGroup.modifySet),
+      ),
+    })),
+    newRemoteEvents: newRemoteEvents.map((remote) => ({
+      ...remote,
+      conflictType: 'overlap',
+      conflictingEvents: pendingLocalEvents.filter((pending) =>
+        factsIntersect(pending.factsGroup.modifySet, remote.factsGroup.modifySet),
+      ),
+    })),
+    validate: ({ rebasedLocalEvents, mutationDefs }) =>
+      validateFacts({
+        factGroups: rebasedLocalEvents.map((event) =>
+          getFactsGroupForMutationArgs({
+            factsCallback: mutationDefs[event.mutation]!.options.facts,
+            args: event.args,
+            currentFacts: new Map(),
+          }),
+        ),
+        initialSnapshot,
+      }),
+  })
+  const headGlobalId = newRemoteEvents.at(-1)!.id.global
+
+  return rebasedLocalEvents.map(
+    (event, index) =>
+      ({
+        id: { global: headGlobalId + index + 1, local: 0 } satisfies EventId,
+        parentId: { global: headGlobalId + index, local: 0 } satisfies EventId,
+        mutation: event.mutation,
+        args: event.args,
+      }) satisfies MutationEvent.Any,
+  )
+}

package/src/sync/next/test/compact-events.calculator.test.ts

@@ -0,0 +1,121 @@
+import { defineMutation } from '@livestore/common/schema'
+import { Schema } from '@livestore/utils/effect'
+import { describe, expect, it } from 'vitest'
+
+import { compactEvents } from '../compact-events.js'
+import { historyDagFromNodes } from '../history-dag.js'
+import { customSerializer } from './compact-events.test.js'
+import { toEventNodes } from './mutation-fixtures.js'
+
+expect.addSnapshotSerializer(customSerializer)
+
+const compact = (events: any[]) => {
+  const dag = historyDagFromNodes(toEventNodes(events, mutations))
+  const compacted = compactEvents(dag)
+
+  return Array.from(compacted.dag.nodeEntries())
+    .map((_) => _.attributes)
+    .map(({ factsGroup, ...rest }) => ({ ...rest, facts: factsGroup }))
+    .slice(1)
+}
+
+const facts = {
+  multiplyByZero: `multiplyByZero`,
+}
+
+const mutations = {
+  add: defineMutation('add', Schema.Struct({ value: Schema.Number }), 'UPDATE values SET value = value + $value', {}),
+  multiply: defineMutation(
+    'multiply',
+    Schema.Struct({ value: Schema.Number }),
+    'UPDATE values SET value = value * $value',
+    {
+      facts: ({ value }, currentFacts) => ({
+        modify: {
+          set: value === 0 || currentFacts.has(facts.multiplyByZero) ? [facts.multiplyByZero] : [],
+          unset: value === 0 ? [] : [facts.multiplyByZero],
+        },
+      }),
+    },
+  ),
+  // TODO divide by zero
+}
+
+describe('compactEvents calculator', () => {
+  it('1 + 1', () => {
+    const expected = compact([
+      mutations.add({ value: 1 }), // 0
+      mutations.add({ value: 1 }), // 1
+    ])
+
+    expect(expected).toMatchInlineSnapshot(`
+      [
+        { id: 0, parentId: -1, mutation: "add", args: { value: 1 }, facts: "" }
+        { id: 1, parentId: 0, mutation: "add", args: { value: 1 }, facts: "" }
+      ]
+    `)
+  })
+
+  it('2 * 2', () => {
+    const expected = compact([
+      mutations.multiply({ value: 2 }), // 0
+      mutations.multiply({ value: 2 }), // 1
+    ])
+
+    expect(expected).toMatchInlineSnapshot(`
+      [
+        { id: 0, parentId: -1, mutation: "multiply", args: { value: 2 }, facts: "?multiplyByZero -multiplyByZero" }
+        { id: 1, parentId: 0, mutation: "multiply", args: { value: 2 }, facts: "?multiplyByZero -multiplyByZero" }
+      ]
+    `)
+  })
+
+  it('2 * 2 * 0', () => {
+    const expected = compact([
+      mutations.multiply({ value: 2 }), // 0
+      mutations.multiply({ value: 2 }), // 1
+      mutations.multiply({ value: 0 }), // 2
+    ])
+
+    expect(expected).toMatchInlineSnapshot(`
+      [
+        { id: 2, parentId: -1, mutation: "multiply", args: { value: 0 }, facts: "+multiplyByZero" }
+      ]
+    `)
+  })
+
+  it('2 * 2 * 0 + 1', () => {
+    const expected = compact([
+      mutations.multiply({ value: 2 }), // 0
+      mutations.multiply({ value: 2 }), // 1
+      mutations.multiply({ value: 0 }), // 2
+      mutations.add({ value: 1 }), // 3
+    ])
+
+    expect(expected).toMatchInlineSnapshot(`
+      [
+        { id: 2, parentId: -1, mutation: "multiply", args: { value: 0 }, facts: "+multiplyByZero" }
+        { id: 3, parentId: 2, mutation: "add", args: { value: 1 }, facts: "" }
+      ]
+    `)
+  })
+
+  it('1 + 2 * 0 * 2 + 1', () => {
+    const expected = compact([
+      mutations.add({ value: 1 }), // 0
+      mutations.multiply({ value: 2 }), // 1
+      mutations.multiply({ value: 0 }), // 2
+      mutations.multiply({ value: 2 }), // 3
+      mutations.add({ value: 1 }), // 4
+    ])
+
+    expect(expected).toMatchInlineSnapshot(`
+      [
+        { id: 0, parentId: -1, mutation: "add", args: { value: 1 }, facts: "" }
+        { id: 2, parentId: 0, mutation: "multiply", args: { value: 0 }, facts: "+multiplyByZero" }
+        { id: 3, parentId: 2, mutation: "multiply", args: { value: 2 }, facts: "?multiplyByZero +multiplyByZero -multiplyByZero" }
+        { id: 4, parentId: 3, mutation: "add", args: { value: 1 }, facts: "" }
+      ]
+    `)
+  })
+})

package/src/sync/next/test/compact-events.test.ts

@@ -0,0 +1,232 @@
+import type { MutationEventFacts } from '@livestore/common/schema'
+import { describe, expect, it } from 'vitest'
+
+import { compactEvents } from '../compact-events.js'
+import type { HistoryDagNode } from '../history-dag.js'
+import { EMPTY_FACT_VALUE, historyDagFromNodes } from '../history-dag.js'
+import { mutations, toEventNodes } from './mutation-fixtures.js'
+
+const customStringify = (value: any): string => {
+  if (value === null) {
+    return 'null'
+  }
+  const type = typeof value
+
+  if (type === 'string') {
+    return JSON.stringify(value)
+  }
+  if (type === 'number' || type === 'boolean') {
+    return String(value)
+  }
+  if (Array.isArray(value)) {
+    const elements = value.map((el) => customStringify(el))
+    return `[${elements.join(', ')}]`
+  }
+  if (value instanceof Set) {
+    const elements = Array.from(value).map((el) => customStringify(el))
+    return `[${elements.join(', ')}]`
+  }
+  if (value instanceof Map) {
+    const keys = Array.from(value.keys()).map(customStringify).join(', ')
+    return `[${keys}]`
+  }
+  if (type === 'object') {
+    const entries = Object.keys(value).map((key) => {
+      const val = value[key]
+      const valStr =
+        key === 'facts'
+          ? `"${factsToString(val)}"`
+          : (key === 'id' || key === 'parentId') && Object.keys(val).length === 2 && val.local === 0
+            ? val.global
+            : customStringify(val)
+
+      return `${key}: ${valStr}`
+    })
+    return `{ ${entries.join(', ')} }`
+  }
+  return String(value)
+}
+
+const factsToString = (facts: HistoryDagNode['factsGroup']) =>
+  [
+    factsSetToString(facts.depRequire, '↖'),
+    factsSetToString(facts.depRead, '?'),
+    factsSetToString(facts.modifySet, '+'),
+    factsSetToString(facts.modifyUnset, '-'),
+  ]
+    .flat()
+    .join(' ')
+
+const factsSetToString = (facts: MutationEventFacts, prefix: string) =>
+  Array.from(facts.entries()).map(([key, value]) => prefix + key + (value === EMPTY_FACT_VALUE ? '' : `=${value}`))
+
+export const customSerializer = {
+  test: (val: unknown) => Array.isArray(val),
+  print: (val: unknown[], _serialize: (item: unknown) => string) => {
+    return '[\n' + (val as any[]).map((item) => '  ' + customStringify(item)).join('\n') + '\n]'
+  },
+} as any
+
+expect.addSnapshotSerializer(customSerializer)
+
+const compact = (events: any[]) => {
+  const dag = historyDagFromNodes(toEventNodes(events, mutations))
+  const compacted = compactEvents(dag)
+
+  return Array.from(compacted.dag.nodeEntries())
+    .map((_) => _.attributes)
+    .map(({ factsGroup, ...rest }) => ({ ...rest, facts: factsGroup }))
+    .slice(1)
+}
+
+describe('compactEvents todo app', () => {
+  it('completeTodo', () => {
+    const expected = compact([
+      mutations.createTodo({ id: 'A', text: 'buy milk' }), // 0
+      mutations.completeTodo({ id: 'A' }), // 1
+      mutations.completeTodo({ id: 'A' }), // 2
+    ])
+
+    expect(expected).toMatchInlineSnapshot(`
+      [
+        { id: 0, parentId: -1, mutation: "createTodo", args: { id: "A", text: "buy milk" }, facts: "+todo-exists-A +todo-is-writeable-A=true +todo-completed-A=false" }
+        { id: 2, parentId: 0, mutation: "completeTodo", args: { id: "A" }, facts: "↖todo-exists-A ↖todo-is-writeable-A=true +todo-completed-A=true" }
+      ]
+    `)
+  })
+
+  it('toggleTodo', () => {
+    const expected = compact([
+      mutations.createTodo({ id: 'A', text: 'buy milk' }), // 0
+      mutations.toggleTodo({ id: 'A' }), // 1
+      mutations.toggleTodo({ id: 'A' }), // 2
+      mutations.toggleTodo({ id: 'A' }), // 3
+    ])
+
+    expect(expected).toMatchInlineSnapshot(`
+      [
+        { id: 0, parentId: -1, mutation: "createTodo", args: { id: "A", text: "buy milk" }, facts: "+todo-exists-A +todo-is-writeable-A=true +todo-completed-A=false" }
+        { id: 1, parentId: 0, mutation: "toggleTodo", args: { id: "A" }, facts: "↖todo-exists-A ↖todo-is-writeable-A=true ?todo-completed-A +todo-completed-A=true" }
+        { id: 2, parentId: 1, mutation: "toggleTodo", args: { id: "A" }, facts: "↖todo-exists-A ↖todo-is-writeable-A=true ?todo-completed-A +todo-completed-A=false" }
+        { id: 3, parentId: 2, mutation: "toggleTodo", args: { id: "A" }, facts: "↖todo-exists-A ↖todo-is-writeable-A=true ?todo-completed-A +todo-completed-A=true" }
+      ]
+    `)
+  })
+
+  it('completeTodo / toggleTodo', () => {
+    const expected = compact([
+      mutations.createTodo({ id: 'A', text: 'buy milk' }), // 0
+      mutations.toggleTodo({ id: 'A' }), // 1
+      mutations.toggleTodo({ id: 'A' }), // 2
+      mutations.completeTodo({ id: 'A' }), // 3
+      mutations.completeTodo({ id: 'A' }), // 4
+      mutations.toggleTodo({ id: 'A' }), // 5
+    ])
+
+    expect(expected).toMatchInlineSnapshot(`
+      [
+        { id: 0, parentId: -1, mutation: "createTodo", args: { id: "A", text: "buy milk" }, facts: "+todo-exists-A +todo-is-writeable-A=true +todo-completed-A=false" }
+        { id: 4, parentId: 0, mutation: "completeTodo", args: { id: "A" }, facts: "↖todo-exists-A ↖todo-is-writeable-A=true +todo-completed-A=true" }
+        { id: 5, parentId: 4, mutation: "toggleTodo", args: { id: "A" }, facts: "↖todo-exists-A ↖todo-is-writeable-A=true ?todo-completed-A +todo-completed-A=false" }
+      ]
+    `)
+  })
+
+  it('readonly setTextTodo', () => {
+    const expected = compact([
+      mutations.createTodo({ id: 'A', text: 'buy milk' }), // 0
+      mutations.setReadonlyTodo({ id: 'A', readonly: false }), // 1
+      mutations.setTextTodo({ id: 'A', text: 'buy soy milk' }), // 2
+      mutations.setReadonlyTodo({ id: 'A', readonly: true }), // 3
+    ])
+
+    expect(expected).toMatchInlineSnapshot(`
+      [
+        { id: 0, parentId: -1, mutation: "createTodo", args: { id: "A", text: "buy milk" }, facts: "+todo-exists-A +todo-is-writeable-A=true +todo-completed-A=false" }
+        { id: 1, parentId: 0, mutation: "setReadonlyTodo", args: { id: "A", readonly: false }, facts: "↖todo-exists-A +todo-is-writeable-A=true" }
+        { id: 2, parentId: 1, mutation: "setTextTodo", args: { id: "A", text: "buy soy milk" }, facts: "↖todo-exists-A ↖todo-is-writeable-A=true +todo-text-updated-A" }
+        { id: 3, parentId: 2, mutation: "setReadonlyTodo", args: { id: "A", readonly: true }, facts: "↖todo-exists-A +todo-is-writeable-A=false" }
+      ]
+    `)
+  })
+
+  it('readonly setTextTodo 2', () => {
+    const expected = compact([
+      mutations.createTodo({ id: 'A', text: 'buy milk' }), // 0
+      mutations.setReadonlyTodo({ id: 'A', readonly: false }), // 1
+      mutations.completeTodo({ id: 'A' }), // 2
+      mutations.setTextTodo({ id: 'A', text: 'buy soy milk' }), // 3
+      mutations.setReadonlyTodo({ id: 'A', readonly: true }), // 4
+    ])
+
+    expect(expected).toMatchInlineSnapshot(`
+      [
+        { id: 0, parentId: -1, mutation: "createTodo", args: { id: "A", text: "buy milk" }, facts: "+todo-exists-A +todo-is-writeable-A=true +todo-completed-A=false" }
+        { id: 1, parentId: 0, mutation: "setReadonlyTodo", args: { id: "A", readonly: false }, facts: "↖todo-exists-A +todo-is-writeable-A=true" }
+        { id: 2, parentId: 1, mutation: "completeTodo", args: { id: "A" }, facts: "↖todo-exists-A ↖todo-is-writeable-A=true +todo-completed-A=true" }
+        { id: 3, parentId: 2, mutation: "setTextTodo", args: { id: "A", text: "buy soy milk" }, facts: "↖todo-exists-A ↖todo-is-writeable-A=true +todo-text-updated-A" }
+        { id: 4, parentId: 3, mutation: "setReadonlyTodo", args: { id: "A", readonly: true }, facts: "↖todo-exists-A +todo-is-writeable-A=false" }
+      ]
+    `)
+  })
+
+  it('readonly setTextTodo - should fail', () => {
+    const expected = () =>
+      compact([
+        mutations.createTodo({ id: 'A', text: 'buy milk' }), // 0
+        mutations.setReadonlyTodo({ id: 'A', readonly: false }), // 1
+        mutations.setTextTodo({ id: 'A', text: 'buy soy milk' }), // 2
+        mutations.setReadonlyTodo({ id: 'A', readonly: true }), // 3
+        mutations.setTextTodo({ id: 'A', text: 'buy oat milk' }), // 4
+      ])
+
+    expect(expected).toThrowErrorMatchingInlineSnapshot(`
+      [Error: Mutation setTextTodo requires facts that have not been set yet.
+      Requires: todo-exists-A, todo-is-writeable-A=true
+      Facts Snapshot: todo-exists-A, todo-is-writeable-A=false, todo-completed-A=false, todo-text-updated-A]
+    `)
+  })
+
+  it('completeTodos', () => {
+    const expected = compact([
+      mutations.createTodo({ id: 'A', text: 'buy milk' }), // 0
+      mutations.createTodo({ id: 'B', text: 'buy bread' }), // 1
+      mutations.createTodo({ id: 'C', text: 'buy cheese' }), // 2
+      mutations.completeTodos({ ids: ['A', 'B', 'C'] }), // 3
+      mutations.toggleTodo({ id: 'A' }), // 4
+      mutations.completeTodo({ id: 'A' }), // 5
+    ])
+
+    expect(expected).toMatchInlineSnapshot(`
+      [
+        { id: 0, parentId: -1, mutation: "createTodo", args: { id: "A", text: "buy milk" }, facts: "+todo-exists-A +todo-is-writeable-A=true +todo-completed-A=false" }
+        { id: 1, parentId: 0, mutation: "createTodo", args: { id: "B", text: "buy bread" }, facts: "+todo-exists-B +todo-is-writeable-B=true +todo-completed-B=false" }
+        { id: 2, parentId: 1, mutation: "createTodo", args: { id: "C", text: "buy cheese" }, facts: "+todo-exists-C +todo-is-writeable-C=true +todo-completed-C=false" }
+        { id: 3, parentId: 2, mutation: "completeTodos", args: { ids: ["A", "B", "C"] }, facts: "↖todo-exists-A ↖todo-is-writeable-A=true ↖todo-exists-B ↖todo-is-writeable-B=true ↖todo-exists-C ↖todo-is-writeable-C=true +todo-completed-A=true +todo-completed-B=true +todo-completed-C=true" }
+        { id: 5, parentId: 3, mutation: "completeTodo", args: { id: "A" }, facts: "↖todo-exists-A ↖todo-is-writeable-A=true +todo-completed-A=true" }
+      ]
+    `)
+  })
+
+  it('completeTodos 2', () => {
+    const expected = compact([
+      mutations.createTodo({ id: 'A', text: 'buy milk' }), // 0
+      mutations.createTodo({ id: 'B', text: 'buy bread' }), // 1
+      mutations.createTodo({ id: 'C', text: 'buy cheese' }), // 2
+      mutations.toggleTodo({ id: 'A' }), // 3
+      mutations.completeTodos({ ids: ['A', 'B', 'C'] }), // 4
+      mutations.toggleTodo({ id: 'A' }), // 5
+      mutations.completeTodo({ id: 'A' }), // 6
+    ])
+
+    expect(expected).toMatchInlineSnapshot(`
+      [
+        { id: 0, parentId: -1, mutation: "createTodo", args: { id: "A", text: "buy milk" }, facts: "+todo-exists-A +todo-is-writeable-A=true +todo-completed-A=false" }
+        { id: 1, parentId: 0, mutation: "createTodo", args: { id: "B", text: "buy bread" }, facts: "+todo-exists-B +todo-is-writeable-B=true +todo-completed-B=false" }
+        { id: 2, parentId: 1, mutation: "createTodo", args: { id: "C", text: "buy cheese" }, facts: "+todo-exists-C +todo-is-writeable-C=true +todo-completed-C=false" }
+        { id: 4, parentId: 2, mutation: "completeTodos", args: { ids: ["A", "B", "C"] }, facts: "↖todo-exists-A ↖todo-is-writeable-A=true ↖todo-exists-B ↖todo-is-writeable-B=true ↖todo-exists-C ↖todo-is-writeable-C=true +todo-completed-A=true +todo-completed-B=true +todo-completed-C=true" }
+        { id: 6, parentId: 4, mutation: "completeTodo", args: { id: "A" }, facts: "↖todo-exists-A ↖todo-is-writeable-A=true +todo-completed-A=true" }
+      ]
+    `)
+  })
+})

package/src/sync/next/test/mod.ts

@@ -0,0 +1 @@
+export * from './mutation-fixtures.js'

package/src/sync/next/test/mutation-fixtures.ts

@@ -0,0 +1,230 @@
+import { Schema } from '@livestore/utils/effect'
+
+import { type EventId, ROOT_ID } from '../../../adapter-types.js'
+import type { MutationDef } from '../../../schema/mutations.js'
+import { defineFacts, defineMutation } from '../../../schema/mutations.js'
+import { factsSnapshotForDag, getFactsGroupForMutationArgs } from '../facts.js'
+import type { HistoryDagNode } from '../history-dag.js'
+import { historyDagFromNodes, rootEventNode } from '../history-dag.js'
+
+/** Used for conflict detection and event history compaction */
+export const facts = defineFacts({
+  todoExists: (id: string) => `todo-exists-${id}`,
+  todoIsWriteable: (id: string, writeable: boolean) => [`todo-is-writeable-${id}`, writeable],
+  todoCompleted: (id: string, completed: boolean) => [`todo-completed-${id}`, completed],
+  todoTextUpdated: (id: string) => `todo-text-updated-${id}`,
+  inputValue: (id: string) => `input-value-${id}`,
+})
+
+export const mutations = {
+  createTodo: defineMutation(
+    'createTodo',
+    Schema.Struct({ id: Schema.String, text: Schema.String }),
+    'INSERT INTO todos (id, text) VALUES ($id, $text)',
+    {
+      facts: ({ id }) => ({
+        modify: {
+          set: [facts.todoExists(id), facts.todoIsWriteable(id, true), facts.todoCompleted(id, false)],
+        },
+      }),
+    },
+  ),
+  upsertTodo: defineMutation(
+    'upsertTodo',
+    Schema.Struct({ id: Schema.String, text: Schema.optional(Schema.String) }),
+    'INSERT INTO todos (id, text) VALUES ($id, $text) ON CONFLICT (id) DO UPDATE SET text = $text',
+    {
+      facts: ({ id }, currentFacts) =>
+        // TODO enable an API along the lines of `map.has(key, value)`
+        currentFacts.has(facts.todoExists(id)) && currentFacts.get(facts.todoIsWriteable(id, true)[0]) === false
+          ? { require: [facts.todoExists(id), facts.todoIsWriteable(id, true)] }
+          : { modify: { set: [facts.todoExists(id), facts.todoIsWriteable(id, true), facts.todoTextUpdated(id)] } },
+    },
+  ),
+  completeTodo: defineMutation(
+    'completeTodo',
+    Schema.Struct({ id: Schema.String }),
+    // consider `RETURNING` to validate before applying facts
+    'UPDATE todos SET completed = true WHERE id = $id',
+    {
+      // prewrite assertions from DB
+      // enables more concurrency
+      // turning database inside out
+      // similar to upsert semantics
+      facts: ({ id }) => ({
+        require: [facts.todoExists(id), facts.todoIsWriteable(id, true)],
+        modify: { set: [facts.todoCompleted(id, true)] },
+      }),
+    },
+  ),
+  uncompleteTodo: defineMutation(
+    'uncompleteTodo',
+    Schema.Struct({ id: Schema.String }),
+    'UPDATE todos SET completed = false WHERE id = $id',
+    {
+      facts: ({ id }) => ({
+        require: [facts.todoExists(id), facts.todoIsWriteable(id, true)],
+        modify: { set: [facts.todoCompleted(id, false)] },
+      }),
+    },
+  ),
+  completeTodos: defineMutation(
+    'completeTodos',
+    Schema.Struct({ ids: Schema.Array(Schema.String) }),
+    'UPDATE todos SET completed = true WHERE id IN ($ids:csv)',
+    {
+      facts: ({ ids }) => ({
+        require: ids.flatMap((id) => [facts.todoExists(id), facts.todoIsWriteable(id, true)]),
+        modify: { set: ids.map((id) => facts.todoCompleted(id, true)) },
+      }),
+    },
+  ),
+  toggleTodo: defineMutation(
+    'toggleTodo',
+    Schema.Struct({ id: Schema.String }),
+    'UPDATE todos SET completed = NOT completed WHERE id = $id',
+    {
+      facts: ({ id }, currentFacts) => {
+        const currentIsCompleted = currentFacts.get(facts.todoCompleted(id, true)[0]) === true
+        return {
+          require: [facts.todoExists(id), facts.todoIsWriteable(id, true)],
+          modify: {
+            // remove: [facts.todoCompleted(id, currentIsCompleted)],
+            set: [facts.todoCompleted(id, !currentIsCompleted)],
+          },
+        }
+      },
+    },
+  ),
+  setReadonlyTodo: defineMutation(
+    'setReadonlyTodo',
+    Schema.Struct({ id: Schema.String, readonly: Schema.Boolean }),
+    'UPDATE todos SET readonly = $readonly WHERE id = $id',
+    {
+      facts: ({ id, readonly }) => ({
+        require: [facts.todoExists(id)],
+        modify: { set: [facts.todoIsWriteable(id, !readonly)] },
+      }),
+    },
+  ),
+  setTextTodo: defineMutation(
+    'setTextTodo',
+    Schema.Struct({ id: Schema.String, text: Schema.String }),
+    'UPDATE todos SET text = $text WHERE id = $id',
+    {
+      facts: ({ id }) => ({
+        require: [facts.todoExists(id), facts.todoIsWriteable(id, true)],
+        modify: { set: [facts.todoTextUpdated(id)] },
+      }),
+    },
+  ),
+  setInputValue: defineMutation(
+    'setInputValue',
+    Schema.Struct({ id: Schema.String, text: Schema.String }),
+    'UPDATE todos SET text = $text WHERE id = $id',
+    {
+      localOnly: true,
+      facts: ({ id }) => ({ modify: { set: [facts.inputValue(id)] } }),
+    },
+  ),
+}
+
+export type PartialEvent = { mutation: string; args: any }
+
+export const toEventNodes = (
+  partialEvents: PartialEvent[],
+  mutationDefs: Record<string, MutationDef.Any>,
+): HistoryDagNode[] => {
+  const nodesAcc: HistoryDagNode[] = [rootEventNode]
+
+  let currentEventId: EventId = ROOT_ID
+
+  const getNextEventId = (mutationDef: MutationDef.Any): EventId => {
+    if (mutationDef.options.localOnly) {
+      return { global: currentEventId.global, local: currentEventId.local + 1 }
+    }
+    return { global: currentEventId.global + 1, local: 0 }
+  }
+
+  const eventNodes = partialEvents.map((partialEvent) => {
+    const mutationDef = mutationDefs[partialEvent.mutation]!
+    const eventId = getNextEventId(mutationDef)
+    currentEventId = eventId
+
+    const factsSnapshot = factsSnapshotForDag(historyDagFromNodes(nodesAcc, { skipFactsCheck: true }), undefined)
+    // console.log('factsSnapshot', eventId, factsSnapshot)
+    // const depRead: MutationEventFactsSnapshot = new Map<string, any>()
+    // const factsSnapshotProxy = new Proxy(factsSnapshot, {
+    //   get: (target, prop) => {
+    //     if (prop === 'has') {
+    //       return (key: string) => {
+    //         depRead.set(key, EMPTY_FACT_VALUE)
+    //         return target.has(key)
+    //       }
+    //     } else if (prop === 'get') {
+    //       return (key: string) => {
+    //         depRead.set(key, EMPTY_FACT_VALUE)
+    //         return target.get(key)
+    //       }
+    //     }
+
+    //     notYetImplemented(`toEventNodes: ${prop.toString()} is not yet implemented`)
+    //   },
+    // })
+
+    // const factsRes = mutationDef.options.facts?.(partialEvent.args, factsSnapshotProxy)
+    // console.log('factsRes', factsRes?.modify, factsRes?.require)
+    // const iterableToMap = (iterable: Iterable<MutationEventFactInput>) => {
+    //   const map = new Map()
+    //   for (const item of iterable) {
+    //     if (typeof item === 'string') {
+    //       map.set(item, EMPTY_FACT_VALUE)
+    //     } else {
+    //       map.set(item[0], item[1])
+    //     }
+    //   }
+    //   return map
+    // }
+    // const facts = {
+    //   modifyAdd: factsRes?.modify.add ? iterableToMap(factsRes.modify.add) : new Map(),
+    //   modifyRemove: factsRes?.modify.remove ? iterableToMap(factsRes.modify.remove) : new Map(),
+    //   depRequire: factsRes?.require ? iterableToMap(factsRes.require) : new Map(),
+    //   depRead,
+    // } satisfies MutationEventFactsGroup
+
+    // applyFactGroup(facts, factsSnapshot)
+
+    const facts = getFactsGroupForMutationArgs({
+      factsCallback: mutationDef.options.facts,
+      args: partialEvent.args,
+      currentFacts: factsSnapshot,
+    })
+
+    const node = {
+      id: eventId,
+      parentId: getParentId(eventId),
+      mutation: partialEvent.mutation,
+      args: partialEvent.args,
+      factsGroup: facts,
+    } satisfies HistoryDagNode
+    nodesAcc.push(node)
+    return node
+  })
+
+  eventNodes.unshift(rootEventNode as never)
+
+  // console.log('eventNodes', eventNodes)
+
+  return eventNodes
+}
+
+const getParentId = (eventId: EventId): EventId => {
+  const globalParentId = eventId.global
+  const localParentId = eventId.local - 1
+
+  if (localParentId < 0) {
+    return { global: globalParentId - 1, local: 0 }
+  }
+
+  return { global: globalParentId, local: localParentId }
+}