generation.go

package qi

import (
	"encoding/json"
	"errors"
	"fmt"

	"github.com/iamseth/yin"
)

const (
	// DefaultDocumentID identifies the single document used by the demo CLI.
	DefaultDocumentID = "default"
	// InitialGeneration is the first checkpoint generation.
	InitialGeneration       uint64 = 1
	checkpointFormatVersion        = 1
)

var (
	// ErrDocumentMismatch means an artifact was routed to a different document.
	ErrDocumentMismatch = errors.New("qi: document mismatch")
	// ErrGenerationMismatch means an artifact belongs to another checkpoint generation.
	ErrGenerationMismatch = errors.New("qi: generation mismatch")
	// ErrMalformedSyncArtifact distinguishes invalid artifact or yin bytes from identity mismatches.
	ErrMalformedSyncArtifact = errors.New("qi: malformed sync artifact")
)

// DocumentIdentity is the compatibility boundary for one synchronized document.
// DocumentID is stable for the document's lifetime; Generation increases on
// checkpoint rotation and is never inferred from yin causal versions.
type DocumentIdentity struct {
	DocumentID string `json:"document_id"`
	Generation uint64 `json:"generation"`
}

// Cursor is generation-scoped causal coverage. A version vector without this
// identity must never be used for extraction in another generation.
type Cursor struct {
	Identity DocumentIdentity  `json:"identity"`
	Version  yin.VersionVector `json:"version"`
}

// DeltaArtifact associates encoded yin delta bytes with their document generation.
type DeltaArtifact struct {
	Identity DocumentIdentity `json:"identity"`
	Payload  []byte           `json:"payload"`
}

// SnapshotArtifact associates a durable yin snapshot with its document generation.
type SnapshotArtifact struct {
	FormatVersion int              `json:"format_version"`
	Identity      DocumentIdentity `json:"identity"`
	Payload       []byte           `json:"payload"`
}

// CatchUp contains at most one generation-sensitive artifact. A snapshot means
// the requester must bootstrap; a delta is normal same-generation catch-up.
type CatchUp struct {
	Snapshot *SnapshotArtifact `json:"snapshot,omitempty"`
	Delta    *DeltaArtifact    `json:"delta,omitempty"`
}

func validateIdentity(identity DocumentIdentity) error {
	if identity.DocumentID == "" {
		return fmt.Errorf("%w: empty document id", ErrMalformedSyncArtifact)
	}
	if identity.Generation == 0 {
		return fmt.Errorf("%w: zero generation", ErrMalformedSyncArtifact)
	}
	return nil
}

// encodeDelta encodes a yin delta with qi's canonical JSON LWW-map codec. It
// is the single site that selects the typed generic codec for encoding.
func encodeDelta(delta yin.Delta) ([]byte, error) {
	return yin.NewJSONLWWMapDeltaCodec[json.RawMessage]().EncodeDelta(delta)
}

// decodeDelta decodes bytes with qi's canonical JSON LWW-map codec and wraps a
// decode failure as ErrMalformedSyncArtifact, the uniform class for a correctly
// routed artifact carrying invalid yin bytes.
func decodeDelta(data []byte) (yin.Delta, error) {
	delta, err := yin.NewJSONLWWMapDeltaCodec[json.RawMessage]().DecodeDelta(data)
	if err != nil {
		return nil, fmt.Errorf("%w: yin delta: %w", ErrMalformedSyncArtifact, err)
	}
	return delta, nil
}

func compareIdentity(current, incoming DocumentIdentity) error {
	if err := validateIdentity(incoming); err != nil {
		return err
	}
	if current.DocumentID != incoming.DocumentID {
		return fmt.Errorf("%w: have %q, artifact has %q", ErrDocumentMismatch, current.DocumentID, incoming.DocumentID)
	}
	if current.Generation != incoming.Generation {
		return fmt.Errorf("%w: have %s generation %d, artifact has generation %d", ErrGenerationMismatch, current.DocumentID, current.Generation, incoming.Generation)
	}
	return nil
}