Skip to content

Default hub layout to V2 (event-sourced CRDT) #288

@maxine-at-forecast

Description

@maxine-at-forecast

Summary

New repos initialized with crosslink init currently get V1 hub layout (flat locks.json, monolithic issues). V2 (event-sourced CRDT with per-agent events, per-lock files, and compaction) is available but requires an explicit crosslink migrate-hub.

We should make V2 the default for new repos.

Breaking change

This is a breaking change — older crosslink versions that don't understand V2 will fail when encountering a V2 hub. The version marker in meta/version.json causes old agents to exit non-destructively, but they won't be able to participate until upgraded.

Gating criteria

Before flipping the default:

  • Dogfood crosslink migrate-hub on internal repos (start with this repo)
  • Run V2 for at least 2 weeks on internal repos with multi-agent workloads
  • Verify compaction, lock confirmation, and stale detection work smoothly in practice
  • Confirm no regressions in CI (event signing, clock skew detection)
  • Update init_cache() in sync.rs to write V2 layout instead of flat locks.json
  • Add migration guidance to release notes for existing users

Implementation

In sync.rs init_cache(), the orphan branch creation path (line ~337) currently writes locks.json + heartbeats/. Change this to initialize the V2 directory structure (agents/, checkpoint/, locks/, meta/version.json) instead.

Labels

Breaking change, enhancement

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request✨future✨Items that are not on the immediate docket but stashed for a later point

    Type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions