@spec approve_revision(BlogEngine.Context.t(), Ecto.UUID.t(), Ecto.UUID.t()) ::
  {:ok, BlogEngine.Schema.Post.t()} | {:error, term()}

Approves the specified pending revision.

@spec archive(BlogEngine.Context.t(), Ecto.UUID.t()) ::
  {:ok, BlogEngine.Schema.Post.t()} | {:error, term()}

Archives a post without releasing its reserved routes.

@spec change_draft(BlogEngine.Context.t(), Ecto.UUID.t(), map()) ::
  {:ok, Ecto.Changeset.t()} | {:error, BlogEngine.Error.t()}

Builds a validated, non-persisted changeset for a new draft revision.

@spec change_revision(BlogEngine.Context.t(), Ecto.UUID.t(), map()) ::
  {:ok, Ecto.Changeset.t()} | {:error, BlogEngine.Error.t()}

Builds a non-persisting changeset from a post's effective revision.

Unlike change_working_revision/3, this display boundary does not assert that the post is currently editable. Hosts can therefore render consistent read-only forms for pending, archived, or disabled posts. Persistence commands still enforce lifecycle and authorization requirements.

@spec change_working_revision(BlogEngine.Context.t(), Ecto.UUID.t(), map()) ::
  {:ok, Ecto.Changeset.t()} | {:error, BlogEngine.Error.t()}

Builds a validated, non-persisted changeset for a post's editable revision.

@spec create(
  BlogEngine.Context.t(),
  Ecto.UUID.t(),
  map(),
  :draft | :published | :archived
) ::
  {:ok, BlogEngine.Schema.Post.t()} | {:error, term()}

Creates a post and advances it to the requested initial state.

@spec create_draft(BlogEngine.Context.t(), Ecto.UUID.t(), map()) ::
  {:ok, BlogEngine.Schema.Post.t()} | {:error, term()}

Creates a post with a working draft revision.

@spec delete_draft(BlogEngine.Context.t(), Ecto.UUID.t()) :: :ok | {:error, term()}

Deletes a post that has never been published.

@spec get(BlogEngine.Context.t(), Ecto.UUID.t()) ::
  {:ok, BlogEngine.Schema.Post.t()} | {:error, term()}

Gets a tenant-scoped post with its authoring associations loaded.

@spec list(BlogEngine.Context.t(), Ecto.UUID.t(), keyword()) ::
  {:ok, BlogEngine.Page.t(BlogEngine.Posts.Summary.t())}
  | {:error, BlogEngine.Error.t()}

Lists tenant- and blog-scoped posts using their working revision when one exists.

Pagination accepts either :page/:per_page or :offset/:limit; page size is bounded at 100. Supported filters are :search, :publication_state, :author_id, and :featured. Pass order: :inserted_desc to select creation order; the default is stable update order.

@spec list_review_queue(BlogEngine.Context.t(), Ecto.UUID.t(), keyword()) ::
  {:ok, BlogEngine.Page.t(BlogEngine.Posts.ReviewEntry.t())}
  | {:error, BlogEngine.Error.t()}

Lists pending, published, and withheld posts for an editorial review queue.

The queue accepts :page and :per_page, with page size bounded at 100.

@spec publish(BlogEngine.Context.t(), Ecto.UUID.t()) ::
  {:ok, BlogEngine.Schema.Post.t()} | {:error, term()}

Publishes an eligible working revision.

@spec reject_revision(
  BlogEngine.Context.t(),
  Ecto.UUID.t(),
  Ecto.UUID.t(),
  String.t()
) ::
  {:ok, BlogEngine.Schema.Post.t()} | {:error, term()}

Rejects the specified pending revision with a reason.

@spec reopen(BlogEngine.Context.t(), Ecto.UUID.t()) ::
  {:ok, BlogEngine.Schema.Post.t()} | {:error, term()}

Reopens an archived post for editing.

@spec restore(BlogEngine.Context.t(), Ecto.UUID.t()) ::
  {:ok, BlogEngine.Schema.Post.t()} | {:error, term()}

Restores a withheld post to its prior public lifecycle.

@spec save(
  BlogEngine.Context.t(),
  Ecto.UUID.t(),
  map(),
  :draft | :published | :archived
) ::
  {:ok, BlogEngine.Schema.Post.t()} | {:error, term()}

Saves a new working revision and advances the post to the requested state.

@spec submit(BlogEngine.Context.t(), Ecto.UUID.t()) ::
  {:ok, BlogEngine.Schema.Post.t()} | {:error, term()}

Submits a post's working revision for review.

@spec unpublish(BlogEngine.Context.t(), Ecto.UUID.t()) ::
  {:ok, BlogEngine.Schema.Post.t()} | {:error, term()}

Returns a published post to draft state while preserving its route history.

@spec update_working_revision(BlogEngine.Context.t(), Ecto.UUID.t(), map()) ::
  {:ok, BlogEngine.Schema.Post.t()} | {:error, term()}

Replaces the editable working revision for a post.

@spec withhold(BlogEngine.Context.t(), Ecto.UUID.t(), String.t() | nil) ::
  {:ok, BlogEngine.Schema.Post.t()} | {:error, term()}

Withholds a post from public reads without discarding publication history.

An optional nonblank reason is recorded in the withheld audit event's metadata. A blank reason is rejected with an :invalid_reason error.