Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -358,6 +358,11 @@ mise install # erlang 28.1, elixir 1.19.0-otp-28,
mix setup # deps, empty db, assets
```

The server must be **PostgreSQL 15 or newer**, in development, CI and production
alike. The curation migration uses column-list referential actions
(`ON DELETE SET NULL (column)`), which older versions reject. On an older server it
stops with an explicit error rather than failing partway through.

That leaves a working app with an **empty** database. Two things are deliberately
not in git and have to arrive another way:

Expand Down
313 changes: 313 additions & 0 deletions docs/curation/persistence-slice-1.md

Large diffs are not rendered by default.

8 changes: 8 additions & 0 deletions lib/devils_dictionary/claims/contributions.ex
Original file line number Diff line number Diff line change
Expand Up @@ -939,6 +939,14 @@ defmodule DevilsDictionary.Claims.Contributions do
end
end

@doc """
The `user` actor of an account, created on first use. It is what every
human decision is recorded against, here and in curation (#196). Call
inside a transaction: the account row is locked while the actor is found or
made.
"""
def account_actor!(%User{} = user), do: actor!(user)

defp actor!(user) do
# Serializes first-use actor creation for this account.
Repo.one!(from u in User, where: u.id == ^user.id, lock: "FOR UPDATE")
Expand Down
43 changes: 43 additions & 0 deletions lib/devils_dictionary/curation/authority.ex
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
defmodule DevilsDictionary.Curation.Authority do
@moduledoc """
Who may act on curation, checked the way `Contributions.review/6` checks a
claim review.

The role is read from the account row under `FOR UPDATE`, so a revocation
that commits first wins. The actor is the account's own `user` actor. A bot
actor is never returned, and a bot never acts as an operator (R1). The
database checks the same rule again on every decision and receipt it
stores.

This is operator authority only. A panel decision is a different
authority, not a person acting (`Publications`).

* `:reviewer`: reviews, activates, admits, and publishes or withdraws on
operator authority. The account's `reviewer` flag.
* `:author`: provisions compositions, changes scopes, and writes manual
versions. A reviewer or an internal contributor.

Call inside a transaction.
"""

import Ecto.Query

alias DevilsDictionary.Accounts.User
alias DevilsDictionary.Claims.Contributions
alias DevilsDictionary.Repo

@doc "The acting account's actor, or `{:error, :unauthorized}`."
def actor(scope, role) when role in [:reviewer, :author] do
with %{user: %{id: id}} <- scope,
%User{} = user <- Repo.one(from u in User, where: u.id == ^id, lock: "FOR UPDATE"),
true <- permitted?(user, role) do
{:ok, Contributions.account_actor!(user)}
else
_ -> {:error, :unauthorized}
end
end

defp permitted?(%User{reviewer: true}, _role), do: true
defp permitted?(%User{internal_contributor: true}, :author), do: true
defp permitted?(_user, _role), do: false
end
28 changes: 28 additions & 0 deletions lib/devils_dictionary/curation/composition.ex
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
defmodule DevilsDictionary.Curation.Composition do
@moduledoc """
A configuration-scoped editorial composition (#196).

Its identity is `(scope_kind, scope_signature, language_tag,
curation_configuration_id)`. That is the configuration, never its version.
Two configurations over one scope are two compositions, with independent
histories, pointers and clocks (K1).

`scope_signature` is the SHA-256 of its sorted memberships, never a spelling
or a slug (K2). `current_published_version_id` moves only with a publication
receipt (R3).
"""
use Ecto.Schema

schema "editorial_compositions" do
field :curation_configuration_id, :id
field :scope_kind, Ecto.Enum, values: [:lexical_page, :lexeme]
field :language_tag, :string
field :scope_signature, :string
field :state, Ecto.Enum, values: [:active, :retired], default: :active
field :current_published_version_id, :id
field :lock_version, :integer, default: 1
field :created_by_actor_id, :id

timestamps(type: :utc_datetime_usec)
end
end
53 changes: 53 additions & 0 deletions lib/devils_dictionary/curation/composition_item.ex
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
defmodule DevilsDictionary.Curation.CompositionItem do
@moduledoc """
One lead or highlight of a composition version, as exact references.

An item stores ids, hashes and locators, never source text (R7):

* `:content`: a content revision of `item_object_id`;
* `:sense_quotation`: a sense revision, the `quotation:N` locator of one
example, and the SHA-256 of its words;
* `:work`: a source-record revision, or a committed catalog manifest
pinned by name, checksum and row identity.

When a referenced source row is deleted, the database nulls the reference
and the reader withholds the item. Nothing else about an item ever changes.

`required_references` is written by the database at insert: the reference
columns the item was made with. It is what tells a claim or object that a
deletion removed apart from one the item never had, so a deletion can
never make a withheld item eligible again.

A note is attributed to `note_author_actor_id`, the actor who wrote it,
under that actor's own label. The database checks both; a caller never
supplies attribution.
"""
use Ecto.Schema

schema "editorial_composition_items" do
field :composition_version_id, :id
field :role, Ecto.Enum, values: [:lead, :highlight]
field :position, :integer
field :item_kind, Ecto.Enum, values: [:content, :sense_quotation, :work]
field :item_object_id, :id
field :content_revision_id, :id
field :sense_revision_id, :id
field :source_record_revision_id, :id
field :catalog_manifest, :string
field :catalog_checksum, :string
field :catalog_identity, :string
field :locator, :string
field :words_sha256, :string
field :meaning_sense_revision_id, :id
field :meaning_lexeme_id, :id
field :assertion_revision_id, :id
field :selection_origin, Ecto.Enum, values: [:manual], default: :manual
field :note, :string
field :note_author_kind, Ecto.Enum, values: [:human, :model]
field :note_author_label, :string
field :note_author_actor_id, :id
field :required_references, {:array, :string}, read_after_writes: true

timestamps(type: :utc_datetime_usec, updated_at: false)
end
end
12 changes: 12 additions & 0 deletions lib/devils_dictionary/curation/composition_membership.ex
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
defmodule DevilsDictionary.Curation.CompositionMembership do
@moduledoc "One registry object in a composition's scope. In this slice, only lexemes."
use Ecto.Schema

schema "editorial_composition_memberships" do
field :composition_id, :id
field :object_id, :id
field :role, Ecto.Enum, values: [:lexeme], default: :lexeme

timestamps(type: :utc_datetime_usec, updated_at: false)
end
end
30 changes: 30 additions & 0 deletions lib/devils_dictionary/curation/composition_publication.ex
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
defmodule DevilsDictionary.Curation.CompositionPublication do
@moduledoc """
The authoritative publication receipt (R3, R4). It records the pointer
moving from one version to another, or to none, in the same transaction,
with the review that authorized it and the fingerprint it published.
Append-only.

`authority_kind` names what authorized it. In this slice that is always
`:operator`: a reviewer, and for a publication the version's latest review,
an acceptance. The panel-decision authority
(`docs/curation/persistence-slice-1.md`, "Publication authority") needs
decision records that do not exist yet, and the database refuses it.
"""
use Ecto.Schema

schema "editorial_composition_publications" do
field :composition_id, :id
field :action, Ecto.Enum, values: [:publish, :withdraw]
field :authority_kind, Ecto.Enum, values: [:operator]
field :previous_version_id, :id
field :published_version_id, :id
field :authorizing_review_id, :id
field :actor_id, :id
field :reason, :string
field :eligibility_fingerprint, :string
field :idempotency_key, :string

timestamps(type: :utc_datetime_usec, inserted_at: :committed_at, updated_at: false)
end
end
26 changes: 26 additions & 0 deletions lib/devils_dictionary/curation/composition_review.ex
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
defmodule DevilsDictionary.Curation.CompositionReview do
@moduledoc """
A human presentation decision about one composition version (R1, R2).
Append-only; the latest decision is the version's state.

Accepting a presentation is not publishing it, and it accepts no claim or
page. It writes no pointer, no receipt, no assertion review and no page row.
"""
use Ecto.Schema

@decisions [:accepted, :rejected, :withdrawn, :needs_review]

schema "editorial_composition_reviews" do
field :composition_id, :id
field :composition_version_id, :id
field :reviewer_actor_id, :id
field :decision, Ecto.Enum, values: @decisions
field :reason, :string
field :reviewed_eligibility_fingerprint, :string
field :idempotency_key, :string

timestamps(type: :utc_datetime_usec, updated_at: false)
end

def decisions, do: @decisions
end
36 changes: 36 additions & 0 deletions lib/devils_dictionary/curation/composition_version.ex
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
defmodule DevilsDictionary.Curation.CompositionVersion do
@moduledoc """
One immutable arrangement of a composition (#196): at most one lead and
three highlights, frozen against a configuration version and a scope.

Manual only in this slice (K9). `origin` is `manual`, the author is a human
account, and there is no run, participant or ballot. The database checks
`arrangement_hash` against the items at commit (K5).

`eligibility_fingerprint` records the items' eligibility when the version
was made. A review accepts that fingerprint and a publication publishes it
(R4).
"""
use Ecto.Schema

alias DevilsDictionary.Types.JsonValue

schema "editorial_composition_versions" do
field :composition_id, :id
field :curation_configuration_id, :id
field :configuration_version_id, :id
field :version, :integer
field :parent_version_id, :id
field :origin, Ecto.Enum, values: [:manual], default: :manual
field :change_reason, :string
field :created_by_actor_id, :id
field :scope_signature, :string
field :scope_members, JsonValue
field :resolution, :map
field :lead_policy, Ecto.Enum, values: [:bierce_first_v1]
field :arrangement_hash, :string
field :eligibility_fingerprint, :string

timestamps(type: :utc_datetime_usec, updated_at: false)
end
end
Loading