crdt

type Change struct {
	// Message is recorded in the change, for history: the principal the
	// engine acted for and why ("import", "file changed", "save").
	Message string
	// Time is the change's timestamp in Unix milliseconds; zero records
	// none.
	Time int64
}

type Conflict struct {
	Path   string
	Values []any
}

type Doc interface {
	// JSON materialises the document: maps as objects, lists as arrays,
	// texts and scalar strings as strings, counters as numbers.
	JSON() (map[string]any, error)
	// Reconcile makes the document equal to doc with the fewest changes,
	// following shape, and records them as one change. It reports
	// whether anything changed.
	Reconcile(doc map[string]any, shape Shape, meta Change) (bool, error)
	// Heads returns the current heads.
	Heads() (Heads, error)
	// Conflicts lists every field holding concurrent values.
	Conflicts() ([]Conflict, error)

	// Save returns the whole document, compacted.
	Save() ([]byte, error)
	// SaveIncremental returns the changes since the last Save,
	// SaveIncremental or Load, or nil when there are none. Appending
	// these chunks to a saved document and loading the lot reproduces
	// the document.
	SaveIncremental() ([]byte, error)
	// LoadIncremental applies saved bytes (a snapshot or chunks) to this
	// document. Applying bytes it already holds changes nothing.
	LoadIncremental(data []byte) error

	// GenerateSyncMessage returns the next message for the peer whose
	// state is s, or ok=false when the peer is up to date.
	GenerateSyncMessage(s SyncState) (msg []byte, ok bool, err error)
	// ReceiveSyncMessage applies a message from the peer whose state is
	// s. Changes it carries are applied; their order does not matter.
	ReceiveSyncMessage(s SyncState, msg []byte) error

	// Fork returns an independent copy with a new actor.
	Fork() (Doc, error)
	Close() error
}

type Engine interface {
	// New returns an empty document with a fresh, random actor.
	New() (Doc, error)
	// Load returns a document from saved bytes (a snapshot followed by
	// any chunks), with a fresh, random actor for the changes it makes.
	Load(data []byte) (Doc, error)
	// NewSyncState returns the state for a new peer.
	NewSyncState() (SyncState, error)
	Close() error
}

type Heads []string

type Shape struct {
	// ListKeys names, per list, the field that identifies its items:
	// "/spec/keyResults" -> "id". A pointer segment "*" stands for any
	// index, so "/spec/phases/*/deliverables" covers every phase. An item
	// whose key matches keeps its identity across a reconcile; a list
	// with no key is matched by position.
	ListKeys map[string]string
	// Texts are the string fields edited character by character (and so
	// merged character by character), with "*" for any index. Every
	// other string is a scalar: the last write wins and a concurrent
	// write is kept as a conflict.
	Texts []string
}

type SyncState interface {
	Close() error
}