store

type AppendInput struct {
	ContextID  string
	ProducerID string
	Kind       string
	Priority   string // normal | urgent
	Payload    string // opaque JSON
	DedupKey   string
}

type Context struct {
	ID         string
	IncidentID string // optional business key (RCA sid / alarm id), kept as its own field
	Title      string
	CreatorID  string
	Status     string // open | closed
	TokenVer   int
	CreatedAt  string
	ClosedAt   string
}

type Event struct {
	Seq        int64  `json:"seq"`
	ContextID  string `json:"context_id"`
	ProducerID string `json:"producer_id"`
	Kind       string `json:"kind,omitempty"`
	Priority   string `json:"priority"`
	Payload    string `json:"payload"`
	CreatedAt  string `json:"created_at"`
}

type Evidence struct {
	EvidenceID string
	ContextID  string
	SHA256     string
	Size       int64
	MediaType  string
	ProducerID string
	CreatedAt  string
}

type Store interface {
	// OpenContext get-or-creates a context recording incidentID (optional business key) and creatorID; created reports whether this call inserted it.
	OpenContext(ctx context.Context, id, incidentID, title, creatorID string) (c Context, created bool, err error)
	// Append inserts one event; on dedup hit returns the existing seq. Rejects closed contexts.
	Append(ctx context.Context, in AppendInput) (seq int64, deduped bool, err error)
	// Pull returns events with seq > since (asc), the max seq returned as next, and urgent count in the remainder.
	Pull(ctx context.Context, contextID string, since int64, kinds []string, limit int) (events []Event, nextSince int64, urgentPending int, err error)
	// Snapshot returns all events (optionally filtered by kind, capped at maxSeq if >0) plus the current max seq.
	Snapshot(ctx context.Context, contextID string, kinds []string, maxSeq int64) (events []Event, curMaxSeq int64, err error)
	// Close marks a context closed and bumps its token version. Idempotent.
	Close(ctx context.Context, contextID string) error
	// PutEvidence stores a blob (after size/quota check) and returns its metadata.
	PutEvidence(ctx context.Context, contextID, producerID, mediaType string, content []byte, maxObject, maxTotal int64) (Evidence, error)
	// GetEvidenceMeta returns metadata only.
	GetEvidenceMeta(ctx context.Context, evidenceID string) (Evidence, error)
	// ReadEvidence returns a byte slice [offset, offset+length) of the blob; length<=0 means to end.
	ReadEvidence(ctx context.Context, evidenceID string, offset, length int64) ([]byte, error)
	// ContextByID returns a context (for token verification against token_ver).
	ContextByID(ctx context.Context, id string) (Context, error)
	// PurgeExpired deletes contexts (and cascaded events/evidence) older than retentionDays. Returns count.
	PurgeExpired(ctx context.Context, retentionDays int) (int, error)
	// Close releases the DB handle.
	CloseDB() error
}