Record the full lifecycle contract in NodeAction entries

A contract comment above NodeAction.record! now specifies every
verb's metadata shape. NodeAction.head_diff computes the publish
diff between an outgoing head and its replacement -- default-locale
title pair always, author/tags pairs and template/assets/abstract/
body flags only when changed, and a per-locale translation_diff
with added/removed/changed status. It is a pure function of its two
pages, shared by publish, rollback, and the future backfill, and
reads translation rows directly so fallbacks never masquerade as
content.

publish entries carry via ("draft" or "revision"); restore_revision!
is now transactional, takes the acting user, and logs through the
same diff. Staged slug/parent changes applied at publish log a move
entry with the path pair. Node creation logs a create entry with
initial title and path. The draft-scoped translation_destroy writer
is retired -- locale removal is recorded by the publish diff, where
it becomes public fact.

9 files changed, 348 insertions, 22 deletions

diff --git a/app/controllers/nodes_controller.rb b/app/controllers/nodes_controller.rb
index ed5f8ef..b66ea49 100644
--- a/app/controllers/nodes_controller.rb
+++ b/app/controllers/nodes_controller.rb
@@ -50,6 +50,9 @@ class NodesController < ApplicationController
       @node.draft.save!
 
       @node.update!(default_template_name: config[:template]) if config && config[:template]
+      NodeAction.record!(:node => @node, :page => @node.draft, :user => current_user,
+                          :action => "create",
+                          :title => params[:title], :path => @node.unique_name)
 
       redirect_to(edit_node_path(@node))
     else
diff --git a/app/controllers/page_translations_controller.rb b/app/controllers/page_translations_controller.rb
index be4f488..38a7c4f 100644
--- a/app/controllers/page_translations_controller.rb
+++ b/app/controllers/page_translations_controller.rb
@@ -63,9 +63,6 @@ class PageTranslationsController < ApplicationController
     draft.translations.where(:locale => @locale).delete_all
     draft.reload
 
-    NodeAction.record!(:node => @node, :page => draft, :user => current_user,
-                        :action => "translation_destroy", :locale => @locale)
-
     flash[:notice] = "#{@locale.upcase} translation removed from the draft. Publish to make this permanent."
     redirect_to node_path(@node)
   rescue LockedByAnotherUser => e
diff --git a/app/controllers/revisions_controller.rb b/app/controllers/revisions_controller.rb
index c5932a4..c1237a9 100644
--- a/app/controllers/revisions_controller.rb
+++ b/app/controllers/revisions_controller.rb
@@ -49,7 +49,7 @@ class RevisionsController < ApplicationController
 
   def restore
     page = Page.find(params[:id])
-    page.node.restore_revision! page.revision
+    page.node.restore_revision! page.revision, current_user
     flash[:notice] = "Revision #{page.revision} restored"
     redirect_to node_path(page.node)
   end
diff --git a/app/models/node.rb b/app/models/node.rb
index b41df06..6ca607d 100644
--- a/app/models/node.rb
+++ b/app/models/node.rb
@@ -194,17 +194,19 @@ class Node < ApplicationRecord
     # Return nil if nothing to publish and no staged changes
     return nil unless self.draft || staged_slug || staged_parent_id
 
+    path_before = self.unique_name
+
     ActiveRecord::Base.transaction do
       if self.draft
-        previous_title = self.head ? Globalize.with_locale(I18n.default_locale) { self.head.title } : nil
+        outgoing_head = self.head
         self.head = self.draft
         self.head.published_at ||= Time.now
         self.head.save!
         self.draft = nil
 
-        new_title = Globalize.with_locale(I18n.default_locale) { self.head.title }
         NodeAction.record!(:node => self, :page => self.head, :user => current_user,
-                            :action => "publish", :from => previous_title, :to => new_title)
+                            :action => "publish", :via => "draft",
+                            **NodeAction.head_diff(outgoing_head, self.head))
       end
 
       if staged_slug && (staged_slug != slug)
@@ -231,17 +233,28 @@ class Node < ApplicationRecord
       self.reload
       self.update_unique_name
       self.send(:update_unique_names_of_children)
+      if self.unique_name != path_before
+        NodeAction.record!(:node => self, :user => current_user, :action => "move",
+                            :path => { "from" => path_before, "to" => self.unique_name })
+      end
       self.unlock!
       self
     end
   end
 
-  def restore_revision! revision
-    if page = self.pages.find_by_revision(revision)
+  def restore_revision! revision, current_user = nil
+    page = self.pages.find_by_revision(revision)
+    return nil unless page
+
+    ActiveRecord::Base.transaction do
+      outgoing_head = self.head
       self.head = page
-      self.save
-    else
-      nil
+      self.save!
+
+      NodeAction.record!(:node => self, :page => page, :user => current_user,
+                          :action => "publish", :via => "revision",
+                          **NodeAction.head_diff(outgoing_head, page))
+      self
     end
   end
 
diff --git a/app/models/node_action.rb b/app/models/node_action.rb
index f32b5b7..39935c7 100644
--- a/app/models/node_action.rb
+++ b/app/models/node_action.rb
@@ -6,6 +6,82 @@ class NodeAction < ApplicationRecord
   validates :action, presence: true
   validates :occurred_at, presence: true
 
+  # == Metadata contract ==
+  #
+  # metadata is written once at creation and never updated. It is the
+  # single place anything that must survive deletion of the referenced
+  # rows lives; node_id/page_id/user_id are lookup and ordering only.
+  # All keys are strings. Pairs are always {"from" => x, "to" => y} --
+  # never _old/_new suffixes. Optional pairs are written only when the
+  # two sides differ; required keys are always present. All titles and
+  # names are read pinned to I18n.default_locale unless inside a
+  # locale-keyed block.
+  #
+  # Baseline, every entry (written here, not by call sites):
+  #   "username"                 -- actor's login at write time
+  #   "human_readable_node_name" -- node title, default locale
+  #
+  # "create":
+  #   "title" -- initial title, default locale
+  #   "path"  -- unique path at creation time. Historical value only:
+  #              later renames/moves do NOT update old entries. Never
+  #              use as a join key; node_id is the join key while the
+  #              node lives.
+  #
+  # "publish" (any promotion of a page to head; the diff against the
+  # outgoing head is computed BEFORE head is re-pointed, over the
+  # union of both pages' locales, by the shared diff function also
+  # used by the backfill):
+  #   "via"    -- "draft" (ordinary publish) | "revision" (rollback
+  #               via restore_revision!). Always written; absent
+  #               means a pre-contract entry.
+  #   "title"  -- pair, always present. "from" is null on a first
+  #               publish (no outgoing head).
+  #   "author" -- pair, only when the byline (page.user) changed
+  #   "tags"   -- pair of arrays, only when changed
+  #   "assets_changed", "template_changed"
+  #            -- booleans, only when true; page_id links to the
+  #               revision for the real diff (never stored here)
+  #   "abstract_changed", "body_changed"
+  #            -- booleans for the default locale, only when true
+  #   "translation_diff" -- only when any non-default locale differs:
+  #     { "<locale>" => {
+  #         "status"           -- "added" | "removed" | "changed"
+  #         "title"            -- pair; "from" null when added,
+  #                               "to" null when removed
+  #         "abstract_changed", "body_changed" -- booleans, only when
+  #                               true, only for status "changed"
+  #     } }
+  #
+  # "move" (reparenting and/or unique-path change; one entry at the
+  # subtree root, descendants get none -- a descendant's own zoomed
+  # view will not show path history):
+  #   "path"  -- pair
+  #
+  # Reserved for the Trash feature, final shape decided there:
+  # "demote" (via "trash" | "depublish"; carries the leaving-public-
+  # view snapshot: head presence, final published_at), "trash",
+  # "restore_from_trash", "destroy" (final path only; publish-state
+  # snapshot lives on the entry that removed it from public view).
+  # Whether trash logs one entry or a trash+demote pair is decided
+  # with that feature.
+  #
+  # Backfilled entries mirror this vocabulary exactly. Their diff
+  # content is computed, not guessed (consecutive revisions still
+  # exist); only actor (from page.editor) and occurred_at are
+  # inferred, and inferred_from names the heuristic per entry
+  # ("from_page_revision", "from_published_at_heuristic").
+  # inferred_from null = witnessed live.
+  #
+  # The "locale" column is currently written by no verb (it belonged
+  # to the retired translation_destroy) and is retained for backfill
+  # or future draft-scoped verbs.
+  #
+  # This log records; it does not undo. Reversibility stays in
+  # restore_revision! and the revisions system. No IP, session, or
+  # user agent, ever. Success only -- rejected attempts are not
+  # logged.
+
   def self.record!(node:, action:, user: nil, page: nil, locale: nil, **extra)
     create!(
       :node        => node,
@@ -23,6 +99,62 @@ class NodeAction < ApplicationRecord
    )
   end
 
+  # Computes the publish-entry diff between an outgoing head and the
+  # page replacing it, in the exact metadata shape the contract above
+  # specifies. Pure function of its two arguments -- shared verbatim by
+  # publish_draft!, restore_revision!, and the backfill task. Reads
+  # translation rows directly, never locale-dependent accessors, so a
+  # fallback value is never mistaken for real content. Returns
+  # symbol-keyed top level for splatting into record!; nested keys are
+  # strings and jsonb serialization stringifies the rest at write time.
+  def self.head_diff old_page, new_page
+    default = I18n.default_locale
+
+    title_of = ->(page) { page&.translations&.find_by(:locale => default)&.title }
+    diff = { :title => { "from" => title_of.call(old_page),
+                         "to"   => title_of.call(new_page) } }
+    return diff unless old_page
+
+    old_author, new_author = old_page.user&.login, new_page.user&.login
+    diff[:author] = { "from" => old_author, "to" => new_author } if old_author != new_author
+
+    old_tags, new_tags = old_page.tag_list.sort, new_page.tag_list.sort
+    diff[:tags] = { "from" => old_tags, "to" => new_tags } if old_tags != new_tags
+
+    diff[:template_changed] = true if old_page.template_name != new_page.template_name
+    diff[:assets_changed]   = true if old_page.assets.map(&:id) != new_page.assets.map(&:id)
+
+    old_t = old_page.translations.find_by(:locale => default)
+    new_t = new_page.translations.find_by(:locale => default)
+    diff[:abstract_changed] = true if old_t&.abstract != new_t&.abstract
+    diff[:body_changed]     = true if old_t&.body != new_t&.body
+
+    locales = (old_page.translated_locales | new_page.translated_locales) - [default]
+    translation_diff = {}
+
+    locales.sort_by(&:to_s).each do |locale|
+      o = old_page.translations.find_by(:locale => locale)
+      n = new_page.translations.find_by(:locale => locale)
+
+      if o.nil?
+        translation_diff[locale.to_s] = { "status" => "added",
+                                          "title" => { "from" => nil, "to" => n.title } }
+      elsif n.nil?
+        translation_diff[locale.to_s] = { "status" => "removed",
+                                          "title" => { "from" => o.title, "to" => nil } }
+      elsif o.title != n.title || o.abstract != n.abstract || o.body != n.body
+        entry = { "status" => "changed" }
+        entry["title"]            = { "from" => o.title, "to" => n.title } if o.title != n.title
+        entry["abstract_changed"] = true if o.abstract != n.abstract
+        entry["body_changed"]     = true if o.body != n.body
+        translation_diff[locale.to_s] = entry
+      end
+    end
+
+    diff[:translation_diff] = translation_diff if translation_diff.any?
+    diff
+  end
+
   def actor_name
     metadata["username"] || "unknown"
   end
diff --git a/test/controllers/nodes_controller_test.rb b/test/controllers/nodes_controller_test.rb
index 9da9514..5b66bd3 100644
--- a/test/controllers/nodes_controller_test.rb
+++ b/test/controllers/nodes_controller_test.rb
@@ -647,4 +647,19 @@ class NodesControllerTest < ActionController::TestCase
     assert_select ".sitemap_node_actions", :text => /Create Child/
     assert_select ".sitemap_node_actions", :text => /Revisions/, :count => 0
   end
+
+  test "create logs a create NodeAction with path and title" do
+    login_as :quentin
+
+    assert_difference "NodeAction.count" do
+      post :create, params: { :kind => "generic", :title => "Brand New", :parent_id => Node.root.id }
+    end
+
+    action = NodeAction.last
+    assert_equal "create",               action.action
+    assert_equal users(:quentin),        action.user
+    assert_equal Node.last,              action.node
+    assert_equal "Brand New",            action.metadata["title"]
+    assert_equal Node.last.unique_name,  action.metadata["path"]
+  end
 end
diff --git a/test/controllers/page_translations_controller_test.rb b/test/controllers/page_translations_controller_test.rb
index 82f8bce..feaacd0 100644
--- a/test/controllers/page_translations_controller_test.rb
+++ b/test/controllers/page_translations_controller_test.rb
@@ -83,18 +83,15 @@ class PageTranslationsControllerTest < ActionController::TestCase
     assert_equal "in progress", Globalize.with_locale(:en) { node.autosave.title }
   end
 
-  test "destroy logs a translation_destroy NodeAction" do
+  test "destroy removes the translation, logs nothing, and redirects" do
     login_as :quentin
     node = Node.root.children.create!(:slug => "translation_destroy_log_test")
     Globalize.with_locale(:en) { node.draft.update!(:title => "English title") }
 
-    delete :destroy, params: { :node_id => node.id, :translation_locale => "en" }
+    assert_no_difference "NodeAction.count" do
+      delete :destroy, params: { :node_id => node.id, :translation_locale => "en" }
+    end
 
-    action = NodeAction.last
-    assert_equal node, action.node
-    assert_equal "en", action.locale
-    assert_equal "translation_destroy", action.action
-    assert_equal users(:quentin), action.user
     assert_redirected_to node_path(node)
   end
 end
diff --git a/test/models/node_action_test.rb b/test/models/node_action_test.rb
new file mode 100644
index 0000000..24d8245
--- /dev/null
+++ b/test/models/node_action_test.rb
@@ -0,0 +1,112 @@
+require "test_helper"
+
+class NodeActionTest < ActiveSupport::TestCase
+
+  # Standalone pages, no node -- same pattern autosave relies on.
+  # Default-locale attributes are written pinned, never ambient.
+  def build_page en: nil, **attrs
+    page = Globalize.with_locale(I18n.default_locale) do
+      Page.create!({ :title => "Titel" }.merge(attrs))
+    end
+    page.translations.create!({ :locale => "en" }.merge(en)) if en
+    page.reload
+  end
+
+  test "first publish yields exactly the title pair, from nil" do
+    diff = NodeAction.head_diff(nil, build_page(:title => "Erstausgabe"))
+
+    assert_equal({ :title => { "from" => nil, "to" => "Erstausgabe" } }, diff)
+  end
+
+  test "title pair is always present, even when unchanged" do
+    diff = NodeAction.head_diff(build_page, build_page)
+
+    assert_equal "Titel", diff[:title]["from"]
+    assert_equal "Titel", diff[:title]["to"]
+  end
+
+  test "author pair present only when the byline changed" do
+    u1, u2 = users(:quentin), users(:aaron)
+
+    assert_nil NodeAction.head_diff(build_page(:user => u1), build_page(:user => u1))[:author]
+
+    changed = NodeAction.head_diff(build_page(:user => u1), build_page(:user => u2))
+    assert_equal({ "from" => u1.login, "to" => u2.login }, changed[:author])
+  end
+
+  test "tags pair present only when the tag set changed" do
+    old_page = build_page; old_page.tag_list = "alpha, beta";  old_page.save!
+    new_page = build_page; new_page.tag_list = "beta, gamma"; new_page.save!
+
+    diff = NodeAction.head_diff(old_page.reload, new_page.reload)
+    assert_equal %w[alpha beta],  diff[:tags]["from"]
+    assert_equal %w[beta gamma], diff[:tags]["to"]
+
+    same = NodeAction.head_diff(old_page, old_page)
+    assert_nil same[:tags]
+  end
+
+  test "template_changed flag only when true" do
+    old_page = build_page(:template_name => "standard_template")
+
+    assert NodeAction.head_diff(old_page, build_page(:template_name => "update"))[:template_changed]
+    assert_nil NodeAction.head_diff(old_page, build_page(:template_name => "standard_template"))[:template_changed]
+  end
+
+  test "assets_changed flag when the attached set differs" do
+    asset = Asset.create!(:name => "diff probe",
+                          :upload_file_name    => "test_image.png",
+                          :upload_content_type => "image/png",
+                          :upload_file_size    => 49854,
+                          :upload_updated_at   => Time.current)
+    old_page, new_page = build_page, build_page
+    new_page.related_assets.create!(:asset_id => asset.id, :position => 1)
+
+
+    diff = NodeAction.head_diff(old_page, new_page.reload)
+    assert diff[:assets_changed]
+    assert_nil NodeAction.head_diff(old_page, old_page)[:assets_changed]
+  end
+
+  test "default-locale abstract and body changes become flags, only when true" do
+    diff = NodeAction.head_diff(build_page(:abstract => "a"), build_page(:abstract => "b"))
+
+    assert diff[:abstract_changed]
+    assert_nil diff[:body_changed]
+  end
+
+  test "added locale carries status and the new title" do
+    diff = NodeAction.head_diff(build_page, build_page(en: { :title => "English" }))
+
+    entry = diff[:translation_diff]["en"]
+    assert_equal "added", entry["status"]
+    assert_equal({ "from" => nil, "to" => "English" }, entry["title"])
+  end
+
+  test "removed locale keeps the vanished title" do
+    diff = NodeAction.head_diff(build_page(en: { :title => "English" }), build_page)
+
+    entry = diff[:translation_diff]["en"]
+    assert_equal "removed", entry["status"]
+    assert_equal "English", entry["title"]["from"]
+    assert_nil entry["title"]["to"]
+  end
+
+  test "changed locale carries only what actually differs" do
+    old_page = build_page(en: { :title => "Same", :body => "old" })
+    new_page = build_page(en: { :title => "Same", :body => "new" })
+
+    entry = NodeAction.head_diff(old_page, new_page)[:translation_diff]["en"]
+    assert_equal "changed", entry["status"]
+    assert_nil entry["title"]
+    assert entry["body_changed"]
+    assert_nil entry["abstract_changed"]
+  end
+
+  test "untouched locales are absent; identical pages yield no translation_diff at all" do
+    old_page = build_page(en: { :title => "Same" })
+    new_page = build_page(en: { :title => "Same" })
+
+    assert_nil NodeAction.head_diff(old_page, new_page)[:translation_diff]
+  end
+end
diff --git a/test/models/node_test.rb b/test/models/node_test.rb
index 022fff6..c8e49e5 100644
--- a/test/models/node_test.rb
+++ b/test/models/node_test.rb
@@ -633,6 +633,7 @@ class NodeTest < ActiveSupport::TestCase
     assert_equal node.head, action.page
     assert_equal @user1, action.user
     assert_equal "publish", action.action
+    assert_equal "draft", action.metadata["via"]
   end
 
   test "publish_draft! called with no user logs no actor, not a guessed one" do
@@ -692,7 +693,7 @@ class NodeTest < ActiveSupport::TestCase
     assert_equal count_before, NodeAction.count
   end
 
-  test "publish_draft! records the title's from/to in metadata" do
+  test "publish_draft! records the title diff in metadata" do
     node = create_node_with_published_page
     Globalize.with_locale(:de) { node.head.update!(:title => "Original Title") }
     find_or_create_draft(node, @user1)
@@ -701,7 +702,63 @@ class NodeTest < ActiveSupport::TestCase
     node.publish_draft!(@user1)
 
     action = NodeAction.last
-    assert_equal "Original Title", action.metadata["from"]
-    assert_equal "New Title", action.metadata["to"]
+    assert_equal "draft",          action.metadata["via"]
+    assert_equal "Original Title", action.metadata.dig("title", "from")
+    assert_equal "New Title",      action.metadata.dig("title", "to")
+  end
+
+  test "publishing a staged slug change logs a move with the path pair" do
+    node = create_node_with_published_page
+    path_before = node.unique_name
+    node.staged_slug = "moved-#{node.slug}"
+    node.save!
+    publish_count_before = NodeAction.where(:action => "publish").count
+
+    node.publish_draft!(@user1)
+
+    node.reload
+    assert_not_equal path_before, node.unique_name
+
+    action = NodeAction.where(:action => "move").last
+    assert_equal node,             action.node
+    assert_equal @user1,           action.user
+    assert_equal path_before,      action.metadata.dig("path", "from")
+    assert_equal node.unique_name, action.metadata.dig("path", "to")
+
+    # No draft was pending: path change alone must not fabricate a publish.
+    assert_equal publish_count_before, NodeAction.where(:action => "publish").count
+  end
+
+  test "publishing a draft together with a staged move logs two entries" do
+    node = create_node_with_published_page
+    find_or_create_draft(node, @user1)
+    node.staged_slug = "relocated-#{node.slug}"
+    node.save!
+
+    assert_difference "NodeAction.count", 2 do
+      node.publish_draft!(@user1)
+    end
+
+    assert_equal %w[move publish],
+                 NodeAction.order(:id).last(2).map(&:action).sort
+  end
+
+  test "restore_revision! logs a publish via revision" do
+    node = create_node_with_published_page
+    Globalize.with_locale(:de) { node.head.update!(:title => "First") }
+    first_head = node.head
+    find_or_create_draft(node, @user1)
+    Globalize.with_locale(:de) { node.draft.update!(:title => "Second") }
+    node.publish_draft!(@user1)
+
+    node.restore_revision!(first_head.revision, @user1)
+
+    action = NodeAction.last
+    assert_equal "publish",   action.action
+    assert_equal "revision",  action.metadata["via"]
+    assert_equal first_head,  action.page
+    assert_equal @user1,      action.user
+    assert_equal "Second",    action.metadata.dig("title", "from")
+    assert_equal "First",     action.metadata.dig("title", "to")
   end
 end