plans

type ConflictError struct {
	Name     string
	Expected int
	Current  int
}

type CorruptError struct {
	Scope Scope
	Name  string
	Err   error
}

type CreateRequest struct {
	Ref     Ref
	Content string
	Title   string
	Author  string
	Status  string
}

type DeleteRequest struct {
	Ref             Ref
	ExpectedVersion *int
}

type ExportRequest struct {
	Ref   Ref
	Path  string
	Force bool
}

type ExportResult struct {
	Scope        Scope  `json:"scope"`
	Name         string `json:"name"`
	Path         string `json:"path"`
	Version      *int   `json:"version,omitempty"`
	BytesWritten int    `json:"bytes_written"`
}

type ListOptions struct {
	// SessionID, when non-empty, also includes that session's plan in the
	// listing if one exists. Only the identified session is consulted; plan
	// files left behind by other sessions are never enumerated.
	SessionID string
}

type ListResult struct {
	Plans    []Plan   `json:"plans"`
	Warnings []string `json:"warnings,omitempty"`
}

type NotFoundError struct {
	Scope Scope
	// Name is the plan name or the session ID, matching Scope.
	Name string
}

type Option func(*service)

type Plan struct {
	// Scope tells which plan system the plan lives in.
	Scope Scope `json:"scope"`
	// Name is the canonical identity within the scope: the validated plan
	// name for shared plans, the session ID for session plans.
	Name string `json:"name"`
	// Title, Author, and Status are shared-plan metadata, empty for session
	// plans. Status is a free-form lifecycle label with no fixed vocabulary.
	Title  string `json:"title,omitempty"`
	Author string `json:"author,omitempty"`
	Status string `json:"status,omitempty"`
	// Content is the plan body. List returns metadata only, so Content is
	// empty there; Get populates it.
	Content string `json:"content,omitempty"`
	// Version is the optimistic-lock revision of a shared plan. It is nil for
	// session plans, which have no revisions: nil means version-guarded
	// operations are unsupported, not "version zero".
	Version *int `json:"version,omitempty"`
	// UpdatedAt is the time of the last write: the stored timestamp for
	// shared plans, the plan file's modification time for session plans.
	// Zero when unknown (and then omitted from JSON via omitzero, which
	// consults time.Time.IsZero; omitempty would keep the zero struct).
	UpdatedAt time.Time `json:"updated_at,omitzero"`
	// SessionID is the owning session of a session plan, empty for shared
	// plans.
	SessionID string `json:"session_id,omitempty"`
	// Path is the backing file of a session plan. It is empty for shared
	// plans, whose storage backend is pluggable and opaque.
	Path string `json:"path,omitempty"`
}

type Ref struct {
	Scope     Scope
	Name      string
	SessionID string
}

type Scope string

type Service interface {
	// List returns plan metadata (Content is left empty): every shared plan
	// sorted by name and, when opts.SessionID is set, that session's plan
	// first. A missing session plan is simply not included, never an error.
	List(ctx context.Context, opts ListOptions) (ListResult, error)
	// Get returns the full plan, including content. A missing plan is a
	// *NotFoundError in either scope.
	Get(ctx context.Context, ref Ref) (Plan, error)
	// Create adds a new shared plan; a name that already exists fails with a
	// *ConflictError carrying the current version.
	Create(ctx context.Context, req CreateRequest) (Plan, error)
	// Update replaces the content (and optionally metadata) of an existing
	// shared plan, honouring req.ExpectedVersion.
	Update(ctx context.Context, req UpdateRequest) (Plan, error)
	// SetStatus sets the free-form status of an existing shared plan,
	// honouring req.ExpectedVersion.
	SetStatus(ctx context.Context, req SetStatusRequest) (Plan, error)
	// Delete removes a shared plan, honouring req.ExpectedVersion. Deleting a
	// missing plan is a *NotFoundError.
	Delete(ctx context.Context, req DeleteRequest) error
	// Export writes a plan's content to req.Path, creating parent directories
	// as needed. An existing destination is refused with a *ValidationError
	// and preserved unless req.Force is set, which replaces an existing
	// regular file atomically; directories and non-regular files are always
	// refused.
	Export(ctx context.Context, req ExportRequest) (ExportResult, error)
}

type SetStatusRequest struct {
	Ref             Ref
	Status          string
	ExpectedVersion *int
}

type StorageError struct {
	Scope Scope
	Op    string
	Err   error
}

type UnsupportedError struct {
	Scope  Scope
	Op     string
	Reason string
}

type UpdateRequest struct {
	Ref             Ref
	Content         string
	Title           *string
	Author          *string
	Status          *string
	ExpectedVersion *int
}

type ValidationError struct {
	Message string
}