entity

type CampaignFile struct {
	Campaign CampaignMeta       `yaml:"campaign"`
	Entities []EntityDefinition `yaml:"entities"`
}

type CampaignMeta struct {
	// Name is the campaign's display name.
	Name string `yaml:"name"`

	// Description is a free-text summary of the campaign.
	Description string `yaml:"description"`

	// System is the game system identifier (e.g., "dnd5e", "pf2e", "custom").
	System string `yaml:"system"`
}

type EntityDefinition struct {
	// ID is a unique identifier. Auto-generated if empty during import.
	ID string `yaml:"id" json:"id"`

	// Name is the entity's display name.
	Name string `yaml:"name" json:"name"`

	// Type classifies the entity (npc, location, item, faction, quest, etc.)
	Type EntityType `yaml:"type" json:"type"`

	// Description is a free-text description of the entity.
	Description string `yaml:"description" json:"description"`

	// Properties holds arbitrary key-value metadata.
	Properties map[string]string `yaml:"properties,omitempty" json:"properties,omitempty"`

	// Relationships defines connections to other entities.
	Relationships []RelationshipDef `yaml:"relationships,omitempty" json:"relationships,omitempty"`

	// Tags are searchable labels for categorization.
	Tags []string `yaml:"tags,omitempty" json:"tags,omitempty"`

	// Visibility controls which NPCs can "see" this entity.
	// An empty slice means visible to all.
	Visibility []string `yaml:"visibility,omitempty" json:"visibility,omitempty"`
}

type EntityType string

type ListOptions struct {
	// Type restricts results to entities of this type.
	// An empty value matches all types.
	Type EntityType

	// Tags restricts results to entities that carry all of the specified tags.
	// An empty slice matches all entities regardless of their tags.
	Tags []string
}

type MemStore struct {
	// contains filtered or unexported fields
}

type RelationshipDef struct {
	// TargetID is the ID of the related entity.
	TargetID string `yaml:"target_id" json:"target_id"`

	// TargetName is an alternative to TargetID — resolved by name during import.
	// If both TargetID and TargetName are set, TargetID takes precedence.
	TargetName string `yaml:"target_name,omitempty" json:"target_name,omitempty"`

	// Type describes the relationship (e.g., "lives_in", "owns", "allied_with").
	Type string `yaml:"type" json:"type"`

	// Bidirectional indicates the relationship applies in both directions.
	Bidirectional bool `yaml:"bidirectional,omitempty" json:"bidirectional,omitempty"`
}

type Store interface {
	// Add creates a new entity. Returns the entity with a generated ID if
	// the provided entity's ID is empty.
	// Returns [ErrDuplicateID] if an entity with the same non-empty ID exists.
	Add(ctx context.Context, entity EntityDefinition) (EntityDefinition, error)

	// Get retrieves an entity by ID.
	// Returns [ErrNotFound] when no entity with that ID exists.
	Get(ctx context.Context, id string) (EntityDefinition, error)

	// List returns all entities, optionally filtered by type and/or tags.
	// An empty [ListOptions] returns all entities.
	// Results order is not guaranteed.
	List(ctx context.Context, opts ListOptions) ([]EntityDefinition, error)

	// Update replaces an existing entity definition.
	// The entity's ID must be non-empty.
	// Returns [ErrNotFound] when no entity with that ID exists.
	Update(ctx context.Context, entity EntityDefinition) error

	// Remove deletes an entity by ID.
	// Returns [ErrNotFound] when no entity with that ID exists.
	Remove(ctx context.Context, id string) error

	// BulkImport adds multiple entities atomically.
	// Each entity without an ID gets one auto-generated.
	// Returns the number of entities successfully imported and any error
	// that caused the import to abort early.
	BulkImport(ctx context.Context, entities []EntityDefinition) (int, error)
}