Skip to content

[codex] Align notebook runtime architecture - #1

Merged
aaltshuler merged 2 commits into
mainfrom
codex-runtime-architecture-alignment
May 29, 2026
Merged

[codex] Align notebook runtime architecture#1
aaltshuler merged 2 commits into
mainfrom
codex-runtime-architecture-alignment

Conversation

@aaltshuler

@aaltshuleraaltshuler commented May 29, 2026

Copy link
Copy Markdown
Collaborator

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.

Written for commit 942e913. Summary will update on new commits.

Review in cubic

- web/optimistic-store: epoch-keyed in-flight patch store; ActionList
overlays patches immediately, shows a "saving…" affordance, and the
executor's next run reconciles patches whose clickedAtEpoch predates
the run.
- web/error-classifier + ErrorPanel: regex-tag mutation failures into
conflict / permission / network / engine / validation with a real
headline, body, and remediation; raw payload kept dim for engineers.
- client/http: bind fetch to globalThis so browsers don't throw
"Illegal invocation" when the Client calls it as a method.
- executor: \`{ \$state: "/p", default: "x" }\` falls back to the default
when state is missing/null/empty, so cells aren't empty before a
filter selection.
- web: drop unused @omnigraph/fixture workspace dep that was pulling
Node-only loader code into the browser bundle.
@aaltshuler
aaltshuler merged commit 014842c into mainMay 29, 2026
1 check passed
aaltshuler added a commit that referenced this pull request Jun 25, 2026
- Text/Quote `text_column` is now required (z.string().min(1)) — a Text/Quote
cell with rows but no text column was silently rendering the empty fallback
instead of failing validation. (#3)
- validate: warn when a *required* (non-nullable) catalog param is bound to
$state without a default — it resolves at runtime, which validate can't see,
so flag it rather than passing silently. (#2)
- validate: document that the server-bound checks are intentional — structural
parse already runs offline above; the meaningful ref/param validation needs a
resolvable source by design. (#1, accepted-by-design)
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

@aaltshuler