Skip to content

docs: bring the roadmap up to 0.7.1 - #11

Merged
cardmagic merged 2 commits into
mainfrom
agent/refresh-roadmap
Aug 9, 2026
Merged

docs: bring the roadmap up to 0.7.1#11
cardmagic merged 2 commits into
mainfrom
agent/refresh-roadmap

Conversation

@cardmagic

Copy link
Copy Markdown
Owner

Documentation only. The roadmap still described the delivery story as of 0.5.0, so anyone reading
it today would conclude that batching and state payloads do not exist.

Recorded as implemented

  • Batched component refreshes: components sharing a signed batch: collapse to one browser
    request per revision, served as HTML frames in a JSON envelope.
  • Personalized state payload broadcasts: computed per subscriber under that subscriber's
    authorization context, fenced by actor revision.
  • The JavaScript suite: browser modules covered in CI with Node's test runner and jsdom, with
    every GitHub Actions reference pinned to a commit SHA.
  • Bounded SQLite lock retries outside synchronous deadlines, folded into the existing
    correctness bullet.

Corrected rather than just added

The realtime bullet now states plainly that batch coalescing happens in the browser, not the
broadcast executor, so one commit still sends one Action Cable message per changed observable
even though it costs one browser request. That distinction was implicit in the PR that shipped
batching and deserves to be visible where people evaluate the design.

Milestone 9 no longer reads as untouched. Throughput, synchronous latency, query counts, and
the three reactive delivery paths are measured on SQLite; adapter-specific and end-to-end browser
measurements are not, and the milestone now says exactly that instead of implying either
everything or nothing is done.

The part worth reading

The wake-up bullet now records a measured fact that was not written down anywhere:

Signaling cannot cross process boundaries, so a commit in a web process does not wake a
broadcast executor in a worker process; that delivery waits up to polling_interval, 100 ms by
default. This is the largest remaining term in reactive update latency, and neither batching nor
state payloads reduce it.

WakeUp is a plain in-process Thread::ConditionVariable and polling_interval still defaults
to 0.1. Everything shipped in 0.6.0 and 0.7.0 cut the number of requests, three to one and then
one to zero, but none of it touches that polling delay. Milestone 2 is reworded to say it should
remove the delay rather than shrink it with a smaller interval.

Not included

No version bump. This changes no code and does not warrant a gem release; it can ride along with
whatever ships next.

Validation

bundle exec rake

271 runs, 1055 assertions, 0 failures, with Standard Ruby, RuboCop, RBS, Steep, and Brakeman
clean. No source files changed.

The roadmap still described the delivery story as of 0.5.0. Record batched refreshes, personalized state payloads, the JavaScript suite, pinned actions, and bounded lock retries as implemented; note that batch coalescing happens in the browser, so one commit still sends one Action Cable message per changed observable; and record what the delivery benchmark does and does not measure. Also record that in-process wake-up signaling cannot reach a worker process, which leaves up to polling_interval of delay on every reactive update and is the largest remaining latency term.
@greptile-apps

greptile-apps Bot commented Aug 9, 2026

Copy link
Copy Markdown

Greptile Summary

The roadmap is updated to reflect capabilities delivered through 0.7.1 and to document remaining limitations more precisely.

  • Records batched refreshes, personalized state payloads, bounded SQLite retries, and JavaScript CI coverage.
  • Clarifies browser-side batch coalescing and the cross-process polling delay.
  • Updates benchmark status and remaining browser-module coverage work.

Confidence Score: 5/5

The documentation-only PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename Overview
docs/roadmap.md Updates implemented and partial milestones; the revised JavaScript coverage wording accurately distinguishes the two tested modules from the uncovered individual-refresh module.

Reviews (2): Last reviewed commit: "docs: scope the JavaScript coverage clai..." | Re-trigger Greptile

Comment thread docs/roadmap.md Outdated
Comment on lines +37 to +38
- A JavaScript suite covering the browser modules, run in CI with Node's test
runner and jsdom, with every GitHub Actions reference pinned to a commit SHA

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 JavaScript coverage is overstated

The suite covers state_payload.js and component_batch_refresh.js, but not component_refresh.js, so describing it as covering all browser modules gives readers false confidence that individual component-refresh behavior is tested in CI.

Suggested change
- A JavaScript suite covering the browser modules, run in CI with Node's test
runner and jsdom, with every GitHub Actions reference pinned to a commit SHA
- A JavaScript suite covering the state payload and batched refresh browser
modules, run in CI with Node's test runner and jsdom, with every GitHub
Actions reference pinned to a commit SHA
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs/roadmap.md
Line: 37-38

Comment:
**JavaScript coverage is overstated**

The suite covers `state_payload.js` and `component_batch_refresh.js`, but not `component_refresh.js`, so describing it as covering all browser modules gives readers false confidence that individual component-refresh behavior is tested in CI.

```suggestion
- A JavaScript suite covering the state payload and batched refresh browser
  modules, run in CI with Node's test runner and jsdom, with every GitHub
  Actions reference pinned to a commit SHA
```

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct, and a fair catch on a PR whose entire purpose is accuracy. The suite covers state_payload.js and component_batch_refresh.js; component_refresh.js has no tests, so "the browser modules" overstated it.

Applied your wording in 3537eff, and went one step further: the uncovered module is now recorded under "Partially implemented" rather than only being absent from the completed list, so the gap is visible where someone would look for it.

- Browser module coverage: the state payload and batched refresh modules have
  JavaScript tests; `component_refresh.js`, which drives individual morph
  refreshes, does not.

Writing those tests is the obvious follow-up. I kept this PR documentation-only rather than expanding it into code, since the point was to make the roadmap match reality, not to change reality.

The suite covers state_payload.js and component_batch_refresh.js. component_refresh.js, which drives individual morph refreshes, has no tests, so claiming the suite covers the browser modules overstated it. Name the two covered modules and record the uncovered one as a known gap.
@cardmagic

Copy link
Copy Markdown
Owner Author

@greptileai review

@cardmagic
cardmagic merged commit 4274d51 into main Aug 9, 2026
13 checks passed
@cardmagic
cardmagic deleted the agent/refresh-roadmap branch August 10, 2026 13:52
Sign up for free to 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