History, snapshots, and synchronization

Every committed file change creates durable version metadata. Project snapshots group a meaningful project state for recovery or review. Server also emits ordered project events so connected clients can reconcile changes without continuously polling the full tree.

A client maintains a cursor, applies events in order, and refreshes authoritative metadata when its cursor is stale or an event gap is detected. Delivery can repeat, so reconciliation must be idempotent. Live events announce committed state; the authoritative copy remains in the underlying store.

Restoring a version appends a new current state and preserves the audit trail. Coordinate restores in active projects because other clients may have pending edits. Snapshot before broad changes and test database-plus-blob recovery as a unit.

Run history is separate: it records computations and artifacts, while file history records project content. Reproducing a run may require both.

Event stream

A client authenticates, fetches a project baseline, and opens the Server-Sent Events stream with a cursor and optional filters. Signal envelopes contain event identity, resource scope, actor, time, and trace context. Heartbeats prevent proxies from closing quiet streams.

On reconnect, the client sends its last accepted cursor. Events can repeat across reconnects, so application must be idempotent. An expired cursor response tells the client to refresh the affected filesystem or history scope and start from a new cursor.

File reconciliation

A filesystem signal identifies the project, path, etag or version, and actor. The client compares it with cached metadata and any open dirty buffer. Clean caches can update automatically. A dirty editor needs a compare, save, or discard decision. Rename and delete events update both the tree and open-editor identity.

Coalescing reduces repeated notifications for a hot path. The final committed state still comes from the filesystem API. Clients use the event stream for invalidation and coordination, then read authoritative metadata/content.

Snapshot restore

A snapshot stores immutable version references for the project tree and may link to a parent. Clients should show the affected paths before restore. Restoring changes current file entries and emits normal project signals; connected clients reconcile the result. Snapshot-pinned versions remain retained until the snapshot is removed.

Operations

Monitor active streams, reconnect rate, cursor lag, resume failures, dispatch backlog, and reconciliation fetches. Frequent reconnects often point to proxy idle timeouts or missing heartbeats. Successful metadata writes with no client events point to dispatch trouble; baseline refresh still provides a recovery path.