How work moves through the stack
The most important system behavior appears in the handoff between local editing, hosted review, and remote replay.
8 min read
Local-first
Editing starts without the network
Alice can build durable local work before any hosted review session or origin push exists.
Review boundary
Bob reviews hosted truth
Bob comments on hosted revisions, not on local repo internals or unstable local state.
Critical invariant
Review closure is not origin execution
An approved review still requires explicit replay to origin before the remote workbook has progressed.
The four journeys at a glance
- 1
Alice bootstraps local work
Create a workbook, write data, persist changes, and organize them into repo history.
- 2
Alice sends work for review
Publish a hosted revision so Bob can comment and approve using the hosted shell.
- 3
Alice replays to origin
Use push origin to progress approved lineage against the remote workbook.
- 4
Charlie joins or catches up
Bind to an existing remote workbook, fetch readiness, and pull a clean baseline or replay continuation.
Local-first bootstrap
The first workflow proves that local spreadsheet work is a first-class path, not a degraded offline mode.
- 1
Create and write locally
agent-sheet creates workbook entries, resolves workspace paths, and records local change batches in workspace truth.
- 2
Persist the work
Durable local state lands in `.agent-sheet`, still without any requirement for hosted review or origin sync.
- 3
Stage and commit
sheet-git reads local truth, organizes it into repo objects, and creates workflow-ready history.
- 4
Create a proposal-shaped review unit
The command surface talks about proposals, but the durable workflow truth sits in review sessions and related repo objects.
Outcome: Local work is now reviewable and traceable.
Hosted review flow
Hosted review exists so Bob can operate on a stable, canonical review artifact instead of Alice's private local state.
Most important distinction
An approved hosted review means review closure. It does not mean the remote workbook has accepted the change.
- 1
Push review
sheet-git publishes hosted review truth through the review core and review-host.
- 2
Open, comment, and approve
Bob reads hosted packets and revision-pinned comments through review-host.
- 3
Read back approval state
Alice can inspect local workflow plus hosted truth to understand whether the hosted review has closed.
Outcome: The work may be approved, but origin has not moved yet.
Origin replay and drift recovery
push origin is the merge-authority path. It creates or updates replay runs, replays approved lineage to the remote workbook, and only then records confirmed remote progression.
When David changes the remote workbook directly, Alice does not guess. She runs fetch origin to resolve readiness, then pull origin either materializes the latest remote base or performs a replay continuation if local work must be preserved.
- fetch origin is not a thin status check. It is the readiness decision point.
- pull origin can mean a plain materialization or a replay continuation, depending on readiness state.
- A clean attached baseline must stay clean. The system should not misclassify it as a local draft.
System Context
Reconnect the workflows to actors and product surfaces.
Terms
Look up the vocabulary used throughout the workflow pages.
Previous
Where the system sits
Univer Runner is not one application. It is a coordinated set of local shells, hosted surfaces, and remote authority boundaries.
Next
Which subsystem owns what
The architecture is easiest to operate when you keep shell responsibilities separate from kernel ownership and avoid reading command names as architecture.