Skip to content

refactor(snapshot): add local workspace owner port - #1636

Merged
limityan merged 1 commit into
GCWing:mainfrom
limityan:yanzhn/local-workspace-snapshot-port
Jul 19, 2026
Merged

refactor(snapshot): add local workspace owner port#1636
limityan merged 1 commit into
GCWing:mainfrom
limityan:yanzhn/local-workspace-snapshot-port

Conversation

@limityan

Copy link
Copy Markdown
Collaborator

Summary

  • Introduces one narrow, local-only workspace snapshot owner port for Desktop and CLI Peer Host operations: workspace preparation, affected-file reads, typed session statistics, and file rollback to a turn.
  • Keeps Core as the owner of snapshot management, tool interception, persistence, event production, and workspace runtime state.
  • Keeps host surfaces responsible for protocol projection, remote detection, rollback sequencing, history maintenance, event fanout, and partial-failure reporting.
  • Updates the architecture guidance to make the resulting ownership and non-goals explicit.

Why

After #1634 converged local session controls on the Agent Runtime SDK, snapshot operations still crossed the Core compatibility facade directly from multiple hosts. Snapshot management is local workspace infrastructure rather than an Agent Runtime SDK capability, so placing it in the SDK or generic runtime services would blur ownership and encourage broader checkpoint semantics.

This PR closes that boundary with a focused port whose contract exposes only the stable facts both existing hosts require. It removes duplicated access paths without migrating the snapshot subsystem or expanding the product model.

Product and architecture impact

  • Existing local request and response shapes, rollback ordering, event ordering, and partial-failure behavior remain compatible.
  • Desktop retains its existing remote compatibility projection, while Peer Host remote snapshot requests return an explicit unsupported result; neither surface passes remote workspaces into the local port.
  • Existing initialization, validation, and operation error context remains user-visible, including the established CLI validation category.
  • The provider is resolved lazily per workspace and concurrent first use converges on one initialized snapshot manager.
  • The design remains account-neutral. No account, login, credential, cloud-sync, or user-identity dependency is introduced.
  • Rich history, generic writers, remote snapshots, full checkpoint/rewind semantics, session activity, and snapshot migration into the Agent Runtime SDK or RuntimeServices remain out of scope.

Validation

  • cargo check --workspace
  • cargo test -p bitfun-runtime-ports
  • Focused Core provider, initialization-concurrency, and snapshot-port tests
  • Focused CLI Peer Host snapshot, error-compatibility, rollback-projection, and product-assembly tests
  • Focused Desktop snapshot-adapter and runtime-owner tests
  • Core architecture boundary checker and its self-test
  • Repository hygiene and staged diff checks
  • Independent senior architecture and product-design review completed with final PASS and no remaining blockers

Review focus

  • Confirm the port remains local-only and does not become a general checkpoint or persistence API.
  • Confirm Core and host owners retain their existing responsibilities.
  • Confirm Desktop and Peer Host preserve their intentionally different remote projections without local fallback.

@limityan
limityan merged commit caf3a24 into GCWing:main Jul 19, 2026
5 checks passed
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