sys:session & sys:stage

In keeping with documents all the way down, a session’s staged work is exposed as synthesized, read-only documents that any client can subscribe to with the ordinary document API.

sys:session — the summary

One document summarizing all staged work in the session: one entry per staged document, with enough metadata to render a “pending changes” list — what’s staged, what’s blocked, what would commit.

The entry list is visibility-shaped. If the reader cannot read a target document — because of the connection principal or the session’s own scopes — that target is omitted from stages. The top-level summary still describes the whole changeset, so a UI can tell that commit-affecting work is hidden without learning the hidden targets:

• isDirty and isBlocked include visible and hidden stages.
• hiddenStageCount counts omitted stage entries.
• hasHiddenDirtyStages and hasHiddenBlockedStages say whether hidden work is dirty or blocked.

Visibility is judged against the schemas the session sees, not just the committed ones. A brand-new type whose sys:schema:<type> document is staged in the same session counts as known, and that staged schema’s own access rule decides — so an agent that defines a type and creates an instance of it in one turn can read that instance back before either has committed.

sys:stage:<docId> — the detail

Per staged document, the full picture: the two lanes — the ordered JSON Patch records and the staged Yjs copies — plus base metadata and conflict state. This is what a review UI renders when the user clicks into one pending document.

For a target the reader cannot read, sys:stage:<docId> reads as absent. The detail document carries patches and staged copy references, so it follows the same whole-document visibility rule as the target it describes.

Why synthesized documents?

These documents are projections — computed from the changeset, never written directly. Exposing them as documents means:

• A review sidebar is just another document subscription — same hooks, same reactivity as the rest of the app.
• Devtools and agents introspect staged work with the API they already have.
• No second “session inspection API” to design, version, or learn.

It’s the same trick as sys:index and sys:client-docs-status: when the engine has interesting state, the answer is a document.