[codex] Align notebook runtime architecture

Merged
AA
5mo ago
+2884-1004

Summary

  • Replace @omnigraph/executor with @omnigraph/runtime as the owner of notebook execution, state, actions, mutations, compatibility validation, cancellation, reruns, and optimistic reconciliation.
  • Formalize capability-aware Source adapters and align fixture/server behavior, including server ego decomposition and clear unsupported-feature errors.
  • Thin the web and TUI renderers so they subscribe to runtime snapshots and route state/action handling through the runtime.
  • Add web notebook/source configuration from query params and broaden runtime, source, renderer, and notebook-spec tests.

Notes

This branch also includes the existing local commit 152be7c (Optimistic mutations and classified errors in web app) that was already ahead of origin/main before this architecture commit. The architecture commit moves the optimistic store responsibility into runtime and removes the old web store.

Validation

  • pnpm -r typecheck
  • pnpm -r test
  • pnpm -r build

Summary by cubic

Replaced @omnigraph/executor with @omnigraph/runtime to centralize execution, state, actions, and mutations behind a capability-aware runtime. Web and TUI now subscribe to runtime snapshots; sources declare capabilities; the runtime handles optimistic reconciliation and error routing.

  • New Features

    • Added @omnigraph/runtime: execution, state mirror, dependency invalidation, action dispatch, mutation lifecycle, cancellation/reruns, and optimistic reconciliation.
    • Capability-aware Source API; ServerSource and FixtureSource implement structured queries; raw .gq remains a server-only escape hatch.
    • Web config via query params/localStorage (server URL, token, branch); added mutation error classifier; ActionList shows saving/error via runtime props.
    • Client: bind fetch to globalThis; read() accepts AbortSignal.
  • Migration

    • Replace @omnigraph/executor with @omnigraph/runtime and use createNotebookRuntime.
    • Remove setMutationSource/getMutationSource; the runtime handles the "mutate" action.
    • Update sources to implement capabilities(), read(request, ctx), and mutate(cmd, ctx); keep raw .gq server-only if needed.
    • If assembling lens specs manually, pass runtimeProps (e.g., cell_id); when firing mutations include __cell_id so the runtime can reconcile per-cell state.