@spec all_group_slugs() :: [String.t()]

Every group slug, regardless of status — the set a new slug has to avoid.

idx_publishing_groups_slug is a plain UNIQUE index with no status predicate, so a TRASHED group still owns its slug. A uniqueness probe built from list_groups/1 (active only) therefore handed create_group/1 a slug the insert could not write, and the constraint error surfaced as a bare "already exists" against a group the admin can no longer see.

@spec clear_active_version_if(String.t(), String.t()) :: non_neg_integer()

Clears a post's active_version_uuid ONLY when it still equals expected_uuid — the compare-and-swap StaleFixer's pointer heal needs. A plain write raced concurrent publishes: the fixer judged the pointer stale from an earlier read, a publish moved it to a fresh version in between, and the unconditional clear reverted the publish. Returns the number of rows updated (0 = the pointer moved; do nothing).

@spec clear_url_slug_from_post(String.t(), String.t(), String.t()) :: [String.t()]

Clears a specific url_slug from all content rows of a post. Returns cleared language codes.

@spec count_posts(String.t()) :: non_neg_integer()

Counts non-trashed posts in a group.

@spec create_content(map()) ::
  changeset_or_struct(PhoenixKit.Modules.Publishing.PublishingContent.t())

Creates content for a version/language.

@spec create_group(map()) ::
  changeset_or_struct(PhoenixKit.Modules.Publishing.PublishingGroup.t())

Creates a publishing group.

@spec create_post(map()) ::
  changeset_or_struct(PhoenixKit.Modules.Publishing.PublishingPost.t())

Creates a post within a group.

@spec create_version(map()) ::
  changeset_or_struct(PhoenixKit.Modules.Publishing.PublishingVersion.t())

Creates a new version for a post.

@spec create_version_from(String.t(), pos_integer(), map() | keyword()) ::
  {:ok, PhoenixKit.Modules.Publishing.PublishingVersion.t()} | {:error, term()}

Creates a new version by cloning content from a source version.

Creates a new version row and copies all content rows from the source. Also copies version-level data (featured_image, tags, seo, etc.). Wrapped in a transaction for atomicity.

Returns {:ok, %PublishingVersion{}} or {:error, reason}.

@spec delete_content(PhoenixKit.Modules.Publishing.PublishingContent.t()) ::
  changeset_or_struct(PhoenixKit.Modules.Publishing.PublishingContent.t())

Deletes content.

@spec delete_group(PhoenixKit.Modules.Publishing.PublishingGroup.t()) ::
  changeset_or_struct(PhoenixKit.Modules.Publishing.PublishingGroup.t())

Deletes a group and all its posts (cascade).

@spec delete_post(PhoenixKit.Modules.Publishing.PublishingPost.t()) ::
  changeset_or_struct(PhoenixKit.Modules.Publishing.PublishingPost.t())

Hard-deletes a post and all its versions/contents (cascade).

@spec demote_version_if_orphaned(String.t(), String.t()) :: non_neg_integer()

Demotes a published version to draft ONLY while its post's active_version_uuid is still NULL — the orphan-demotion StaleFixer runs from a possibly-stale snapshot, and an unconditional demote could draft a version a concurrent publish just made live. One atomic statement; returns the number of rows updated.

@spec find_by_previous_url_slug(String.t(), String.t(), String.t()) ::
  PhoenixKit.Modules.Publishing.PublishingContent.t() | nil

Finds content by a previous URL slug (stored in the data.previous_url_slugs JSONB array). Used to issue public 301 redirects from a post's old URL to its current one.

Published-only: matches the post's ACTIVE version exclusively. An unpublished post (no active_version_uuid, or a draft version) is not reachable from a public URL, so redirecting to it would just land the visitor on a 404 — the lookup must not surface those rows. Excludes trashed posts.

@spec find_by_url_slug(String.t(), String.t(), String.t()) ::
  PhoenixKit.Modules.Publishing.PublishingContent.t() | nil

Public URL-slug lookup. Returns at most one published content row for the given group + language + slug, or nil. Excludes trashed posts and unpublished drafts (drafts are never reachable from a public URL — use find_by_url_slug_any_version/3 for the admin/self-healing path).

Tie-break: when two DIFFERENT published posts in the same group happen to share the same custom url_slug (the DB has no unique index on content url_slug across posts; the per-post (group_uuid, slug) index only prevents post-slug collisions), the query is allowed to return multiple rows. The OLDEST (incumbent) post wins (order_by [asc: p.uuid], exploiting UUIDv7's monotonic timestamp encoding — see schema docs for PublishingPost) so the post that owned the slug first keeps its URL; every newer loser's url_slug is auto-renamed with a -2, -3, … suffix so the next request resolves cleanly without crashing on Ecto.MultipleResultsError. This is a best-effort self-healing safety net for collisions that get past the application-level uniqueness check in PhoenixKit.Modules.Publishing.SlugHelpers, not a transactional correctness mechanism — concurrent requests racing on the same collision could each see the un-renamed state; one will eventually win the rename, the rest log warnings. If you see this fire in production it's a signal the upstream uniqueness check was skipped or raced; investigate the create-time path.

@spec find_by_url_slug_any_version(String.t(), String.t(), String.t()) ::
  PhoenixKit.Modules.Publishing.PublishingContent.t() | nil

Internal URL-slug lookup that DOES surface unpublished drafts. Used by the stale-language self-healing flow (StaleFixer) and slug-uniqueness checks (SlugHelpers.url_slug_exists?) that need to see every existing slug, including those on posts that haven't been published yet.

Returns at most one content row. When the slug matches multiple versions of the SAME post (the common case for posts that accumulated drafts), picks the active version when one exists, otherwise the latest draft by version_number. Does NOT auto-rename collisions — drafts may legitimately share slugs while still being authored.

@spec find_post_by_date_time(String.t(), Date.t(), Time.t() | nil) ::
  PhoenixKit.Modules.Publishing.PublishingPost.t() | nil

Finds a post by date and time (timestamp mode, matches hour:minute only).

@spec get_active_version(PhoenixKit.Modules.Publishing.PublishingPost.t()) ::
  PhoenixKit.Modules.Publishing.PublishingVersion.t() | nil

Gets the active (published) version for a post via active_version_uuid.

Reads from the preloaded :active_version association if present (see get_post/2), otherwise falls back to a direct lookup. This keeps callers that received a hand-built struct working while letting the read paths short-circuit the second round trip.

@spec get_content(String.t(), String.t()) ::
  PhoenixKit.Modules.Publishing.PublishingContent.t() | nil

Gets content for a specific version and language.

@spec get_group(String.t()) :: PhoenixKit.Modules.Publishing.PublishingGroup.t() | nil

Gets a group by UUID.

@spec get_group_by_slug(String.t()) ::
  PhoenixKit.Modules.Publishing.PublishingGroup.t() | nil

Gets a group by slug.

@spec get_group_post_by_uuid(String.t(), String.t(), list()) ::
  PhoenixKit.Modules.Publishing.PublishingPost.t() | nil

The same fetch, but only if the post really belongs to group_slug.

Every group-scoped mutation takes a group from the page the caller is on and a uuid from the event they sent, and those two are not checked against each other by get_post_by_uuid/2 — it looks up the uuid alone. A post uuid is not a secret (the public comment form renders one), so the pairing has to be verified rather than assumed: the group decides which cache to rebuild, which topic to broadcast on, and what the audit row says the actor touched. Answering for a post in another group gets all three wrong, and would be a straightforward hole the moment permissions become per-group rather than per-module.

@spec get_latest_version(String.t()) ::
  PhoenixKit.Modules.Publishing.PublishingVersion.t() | nil

Gets the latest version for a post.

@spec get_post(String.t(), String.t()) ::
  PhoenixKit.Modules.Publishing.PublishingPost.t() | nil

Gets a post by group slug and post slug. Excludes trashed posts.

Preloads :active_version so that downstream get_active_version/1 calls read from the in-memory association instead of issuing a second query — the read-then-resolve hot path becomes a single round trip.

@spec get_post_by_datetime(String.t(), Date.t(), Time.t() | nil) ::
  PhoenixKit.Modules.Publishing.PublishingPost.t() | nil

Gets a timestamp-mode post by date and time.

Truncates seconds from the input time since URLs use HH:MM format only, and new posts are stored with seconds zeroed. For older posts with non-zero seconds, falls back to hour:minute matching.

@spec get_post_by_uuid(String.t(), [atom() | tuple()]) ::
  PhoenixKit.Modules.Publishing.PublishingPost.t() | nil

Gets a post by UUID with preloads.

@spec get_version(String.t(), pos_integer()) ::
  PhoenixKit.Modules.Publishing.PublishingVersion.t() | nil

Gets a specific version by post and version number.

@spec get_version_by_uuid(String.t()) ::
  PhoenixKit.Modules.Publishing.PublishingVersion.t() | nil

Fetches a version by its uuid.

@spec list_contents(String.t()) :: [
  PhoenixKit.Modules.Publishing.PublishingContent.t()
]

Lists all content rows for a version.

@spec list_groups(String.t() | nil) :: [
  PhoenixKit.Modules.Publishing.PublishingGroup.t()
]

Lists groups ordered by position. Filters by status (default: active only).

@spec list_languages(String.t()) :: [String.t()]

Lists available languages for a version.

@spec list_posts(String.t(), String.t() | nil) :: [
  PhoenixKit.Modules.Publishing.PublishingPost.t()
]

Lists posts in a group, optionally filtered by status. Excludes trashed by default.

@spec list_posts_for_listing(String.t()) :: [map()]

Lists all posts in a group in listing format (excerpt only, no full content).

Always uses Mapper.to_listing_map/4 which strips content bodies and includes only excerpts. Designed for caching in :persistent_term where data is copied to the reading process heap — keeping entries small matters.

@spec list_posts_slug_mode(String.t(), String.t() | nil) :: [
  PhoenixKit.Modules.Publishing.PublishingPost.t()
]

Lists posts in slug mode (ordered by slug asc).

@spec list_posts_timestamp_mode(String.t(), String.t() | nil, keyword()) :: [
  PhoenixKit.Modules.Publishing.PublishingPost.t()
]

Lists posts in timestamp mode (ordered by date/time desc).

Options:

• :date - Filter to a specific date (Date struct or ISO 8601 string)

@spec list_posts_with_metadata(String.t(), String.t() | nil) :: [map()]

Lists all posts in a group with their latest version metadata.

Returns a list of post maps suitable for listing pages.

@spec list_versions(String.t()) :: [
  PhoenixKit.Modules.Publishing.PublishingVersion.t()
]

Lists all versions for a post, ordered by version number.

@spec lock_group_row!(module(), String.t()) ::
  PhoenixKit.Modules.Publishing.PublishingGroup.t() | nil

Row-locks a group (FOR UPDATE) inside the caller's transaction and returns the fresh row — the group-save equivalent of lock_post_row!/2.

@spec lock_post_row!(module(), String.t()) ::
  PhoenixKit.Modules.Publishing.PublishingPost.t() | nil

Row-locks a post (FOR UPDATE) inside the caller's transaction — the same lock Versions.publish_version/unpublish/delete take, so any writer that acquires it serializes with the publish machinery. Returns the fresh post row (or nil).

@spec next_version_number(String.t()) :: pos_integer()

Gets the next version number for a post.

Uses SELECT ... FOR UPDATE to lock the row and prevent concurrent reads from getting the same number.

@spec previous_url_slug_taken_by_other_post?(
  String.t(),
  String.t(),
  String.t(),
  String.t() | nil
) :: boolean()

Returns true if url_slug is a PREVIOUS slug of another published post in the group+language (i.e. a slug that post's 301 redirect still owns). A new post claiming it would shadow that redirect — current-slug lookup wins over previous-slug lookup — so old URLs would land on the new post instead. M13.

@spec read_post(String.t(), String.t(), String.t() | nil, pos_integer() | nil) ::
  {:ok, map()} | {:error, :not_found}

Reads a full post with its latest version and content for a specific language.

Returns a post map or nil if not found.

@spec read_post_by_datetime(
  String.t(),
  Date.t(),
  Time.t() | nil,
  String.t() | nil,
  pos_integer() | nil
) :: {:ok, map()} | {:error, :not_found}

Reads a timestamp-mode post by date and time instead of slug.

@spec resolve_content(
  [PhoenixKit.Modules.Publishing.PublishingContent.t()],
  String.t() | nil
) ::
  PhoenixKit.Modules.Publishing.PublishingContent.t() | nil

Resolves content for a language from a list of content rows.

Fallback chain: exact language match → site default language → first available.

@spec restore_group(PhoenixKit.Modules.Publishing.PublishingGroup.t()) ::
  changeset_or_struct(PhoenixKit.Modules.Publishing.PublishingGroup.t())

Restores a trashed group by setting status to 'active'.

@spec restore_post(PhoenixKit.Modules.Publishing.PublishingPost.t()) ::
  changeset_or_struct(PhoenixKit.Modules.Publishing.PublishingPost.t())

Restores a trashed post by clearing trashed_at.

@spec search_published_post_uuids(String.t(), [String.t()], String.t(), pos_integer()) ::
  [String.t()]

Post uuids in a group whose ACTIVE PUBLISHED version has content matching query — a case-insensitive substring over per-language title + body — in any of the candidate languages. ILIKE wildcards in the user's input are escaped, so a search for "50%" matches the literal text. Capped at limit.

Returns bare uuids (not post maps) by design: the public search path filters the listing-cache's chronological maps by this set, reusing all the title/URL/language resolution the listing already does.

@spec stream_posts(String.t()) :: Enumerable.t()

Streams every post in a group (including trashed) for batch operations that shouldn't materialise the whole listing in memory.

Caller MUST be inside a Repo.checkout/1 (or an explicit transaction) — Postgres-backed Ecto streams require a checked-out connection. Yields raw %PublishingPost{} structs with :group preloaded; no version/content metadata (callers re-read what they need).

@spec timestamp_slot_taken?(String.t(), Date.t(), Time.t()) :: boolean()

Returns true if the (group, date, minute) timestamp slot is occupied by ANY post — including trashed ones.

get_post_by_datetime/3 filters out trashed posts (correct for serving), but the unique index on (group_uuid, post_date, post_time) includes them (to protect restore). So availability probes must see trashed rows too, otherwise a trashed post's slot looks free, the insert hits the index, and the collision retry can never resolve it.

@spec trash_group(PhoenixKit.Modules.Publishing.PublishingGroup.t()) ::
  changeset_or_struct(PhoenixKit.Modules.Publishing.PublishingGroup.t())

Trashes a group by setting status to 'trashed'.

@spec trash_post(PhoenixKit.Modules.Publishing.PublishingPost.t()) ::
  changeset_or_struct(PhoenixKit.Modules.Publishing.PublishingPost.t())

Trashes a post by setting trashed_at timestamp.

@spec update_content(PhoenixKit.Modules.Publishing.PublishingContent.t(), map()) ::
  changeset_or_struct(PhoenixKit.Modules.Publishing.PublishingContent.t())

Updates content.

@spec update_content_status(String.t(), String.t()) :: {non_neg_integer(), nil}

Bulk-updates the status of all content rows for a version.

@spec update_content_status_except(String.t(), String.t(), String.t()) ::
  {non_neg_integer(), nil}

Bulk-updates the status of all content rows for a version, excluding a specific language.

@spec update_group(PhoenixKit.Modules.Publishing.PublishingGroup.t(), map()) ::
  changeset_or_struct(PhoenixKit.Modules.Publishing.PublishingGroup.t())

Updates a publishing group.

@spec update_post(PhoenixKit.Modules.Publishing.PublishingPost.t(), map()) ::
  changeset_or_struct(PhoenixKit.Modules.Publishing.PublishingPost.t())

Updates a post.

@spec update_version(PhoenixKit.Modules.Publishing.PublishingVersion.t(), map()) ::
  changeset_or_struct(PhoenixKit.Modules.Publishing.PublishingVersion.t())

Updates a version.

@spec upsert_content(map()) ::
  changeset_or_struct(PhoenixKit.Modules.Publishing.PublishingContent.t())

Upserts content by version_id + language using ON CONFLICT.

@spec upsert_group(map()) ::
  changeset_or_struct(PhoenixKit.Modules.Publishing.PublishingGroup.t())

Upserts a group by slug atomically via PostgreSQL ON CONFLICT.

The previous check-then-act version (get_group_by_slug then create or update) had a TOCTOU race: two concurrent callers with the same slug could both observe nil and both attempt to insert, with one crashing on the unique index. This version delegates conflict resolution to PostgreSQL and replaces the mutable columns on hit.

@spec url_slug_taken_by_other_post?(
  String.t(),
  String.t(),
  String.t(),
  String.t() | nil
) :: boolean()

Returns true when a custom url_slug is already taken in this group+language by a post OTHER than exclude_post_slug (any version, incl. drafts).

Used by uniqueness checks: unlike fetching a single row and inspecting it, the exclusion happens in SQL, so a collision can't be masked when the arbitrarily-ordered match happens to be the post being edited.