feat(brain): add schema versioning and entity migration

lib/goodwizard/actions/brain/helpers.ex

@@ -123,12 +123,28 @@ defmodule Goodwizard.Actions.Brain.Helpers do
   def format_error(:path_traversal), do: "Invalid path"
   def format_error(:body_too_large), do: "Body exceeds maximum size"
   def format_error(:update_locked), do: "Entity is locked by another operation"
+
+  def format_error(:migration_required),
+    do: "Migration definition is required when updating a schema"
+
   def format_error(:enoent), do: "File not found"
   def format_error(:eacces), do: "Permission denied"
   def format_error({:duplicate_id, _id}), do: "Duplicate entity ID"
   def format_error({:parse_error, _file, _reason}), do: "Failed to parse entity file"
   def format_error({:schema_resolution_error, _msg}), do: "Schema resolution failed"
 
+  def format_error({:invalid_schema_version, label}),
+    do: "#{label} version must be a positive integer"
+
+  def format_error({:version_mismatch, expected, got}),
+    do: "Version mismatch: expected #{expected}, got #{got}"
+
+  def format_error({:invalid_migration_definition, field}),
+    do: "Invalid migration definition: #{field}"
+
+  def format_error({:migration_version_mismatch, field, expected, got}),
+    do: "Migration #{field} mismatch: expected #{expected}, got #{got}"
+
   def format_error({:validation, errors}) when is_list(errors),
     do: format_validation_errors(errors)
 

lib/goodwizard/actions/brain/migrate_entities.ex

@@ -0,0 +1,53 @@
+defmodule Goodwizard.Actions.Brain.MigrateEntities do
+  @moduledoc """
+  Applies a stored schema migration to all entities of a given type.
+  """
+
+  use Jido.Action,
+    name: "migrate_entities",
+    description: "Migrate entities of a type from one schema version to the next",
+    schema: [
+      entity_type: [
+        type: :string,
+        required: true,
+        doc: "The entity type to migrate (e.g. \"people\", \"companies\")"
+      ],
+      from_version: [
+        type: :integer,
+        required: true,
+        doc: "Source schema version"
+      ],
+      to_version: [
+        type: :integer,
+        required: true,
+        doc: "Target schema version"
+      ],
+      dry_run: [
+        type: :boolean,
+        default: false,
+        doc: "When true, validates and reports diffs without writing files"
+      ]
+    ]
+
+  alias Goodwizard.Actions.Brain.Helpers
+
+  @impl true
+  @spec run(map(), map()) :: {:ok, map()} | {:error, String.t()}
+  def run(params, context) do
+    workspace = Helpers.workspace(context)
+
+    case Goodwizard.Brain.migrate(
+           workspace,
+           params.entity_type,
+           params.from_version,
+           params.to_version,
+           Map.get(params, :dry_run, false)
+         ) do
+      {:ok, summary} ->
+        {:ok, summary}
+
+      {:error, reason} ->
+        {:error, Helpers.format_error(reason)}
+    end
+  end
+end

lib/goodwizard/actions/brain/save_schema.ex

@@ -16,6 +16,12 @@ defmodule Goodwizard.Actions.Brain.SaveSchema do
         type: {:map, :string, :any},
         required: true,
         doc: "A valid JSON Schema object defining the entity structure"
+      ],
+      migration: [
+        type: {:map, :string, :any},
+        required: false,
+        doc:
+          "Optional migration definition map; required when updating an existing schema version"
       ]
     ]
 
@@ -30,7 +36,7 @@ defmodule Goodwizard.Actions.Brain.SaveSchema do
     schema = ensure_metadata_property(params.schema)
 
     with :ok <- validate_schema_structure(schema) do
-      case Schema.save(workspace, params.entity_type, schema) do
+      case Schema.save(workspace, params.entity_type, schema, Map.get(params, :migration)) do
         :ok ->
           Goodwizard.Cache.delete("brain:schema_summaries:#{workspace}")
           tool_msg = regenerate_tools(workspace, params.entity_type)

lib/goodwizard/agent.ex

@@ -79,6 +79,7 @@ defmodule Goodwizard.Agent do
       Goodwizard.Actions.Brain.ListEntities,
       Goodwizard.Actions.Brain.GetSchema,
       Goodwizard.Actions.Brain.SaveSchema,
+      Goodwizard.Actions.Brain.MigrateEntities,
       Goodwizard.Actions.Brain.ListEntityTypes
     ],
     model: "anthropic:claude-sonnet-4-5",

lib/goodwizard/brain.ex

@@ -8,7 +8,7 @@ defmodule Goodwizard.Brain do
 
   require Logger
 
-  alias Goodwizard.Brain.{Entity, Id, Paths, References, Schema, Seeds}
+  alias Goodwizard.Brain.{Entity, Id, Migration, Paths, References, Schema, Seeds}
 
   @system_fields ["id", "created_at", "updated_at"]
   @max_list_entities 1_000
@@ -209,6 +209,25 @@ defmodule Goodwizard.Brain do
     end)
   end
 
+  @doc """
+  Migrates entities for a type from one schema version to the next.
+
+  Loads the migration definition and executes it, or performs a dry-run
+  when `dry_run` is true.
+  """
+  @spec migrate(String.t(), String.t(), integer(), integer(), boolean()) ::
+          {:ok, map()} | {:error, term()}
+  def migrate(workspace, entity_type, from_version, to_version, dry_run \\ false) do
+    with {:ok, migration_definition} <-
+           Migration.load(workspace, entity_type, from_version, to_version) do
+      if dry_run do
+        Migration.dry_run(workspace, entity_type, migration_definition)
+      else
+        Migration.execute(workspace, entity_type, migration_definition)
+      end
+    end
+  end
+
   @doc """
   Lists all entities of a given type.