Skip to content

Define portable mount identity and replay cursor contracts #94

Description

@valiantone

Context

HotMem event ordering currently relies on a database-local SQLite AUTOINCREMENT sequence. That sequence is useful inside one runtime, but it is not a portable statement of which logical mount produced an event, which history it extends, or where a replay should resume after a clone, restore, fork, or database replacement.

What needs to be done

  • Define stable logical mount/workspace identity separately from runtime or replica identity.
  • Define an opaque, versioned replay cursor bound to source identity, base/history identity, scope, and ordered position.
  • Specify clone, restore, fork, replacement, empty-history, stale-base, and incompatible-base behavior.
  • Represent cursor metadata in exports/manifests and validate it before replay.
  • Add fixtures for wrong-source rejection, stale-base rejection, interrupted resume, repeated replay, clone/fork distinction, and legacy histories.

Acceptance criteria

  • A local SQLite sequence is never accepted as a portable cursor without its source/history identity.
  • A consumer can distinguish a clone of the same logical mount from a different mount and from a divergent runtime fork.
  • Replay against the wrong source or base fails before mutation with an actionable diagnostic.
  • Reusing a completed cursor is idempotent.
  • Cursor format is opaque to callers, versioned, serializable, and covered by golden fixtures.
  • The contract explicitly leaves multi-writer ordering and conflict resolution undefined rather than implying support.

Constraints and non-goals

This issue does not implement transport, peer discovery, authentication, online replication, multi-writer clocks, conflict resolution, or hosted coordination.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:designArchitecture, RFC, ADR, roadmaparea:eventsAppend-only event log and /v1/eventsarea:snapshotSnapshot v2 directory format, portability, replayenhancementNew feature or requestmilestone:portable-workspacePortable Workspace Identity and Lossless Clone Foundationv0.2.NEXTCommitted for a future 0.2.x release; not yet pinned to 0.2.4/0.2.5

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions