feat(pluginkit): skip a plugin's migrations when its recorded version is current

.github/workflows/mutation.yml

@@ -0,0 +1,65 @@
+name: mutation
+
+on:
+  pull_request:
+    paths:
+      - "pluginkit/**.go"
+      - "pluginkit/.gremlins.yaml"
+      - "!pluginkit/graphwire/**"
+      - ".github/workflows/mutation.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  pluginkit:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+        working-directory: pluginkit
+    env:
+      BASE: origin/${{ github.base_ref }}
+      GIT_CONFIG_COUNT: "3"
+      GIT_CONFIG_KEY_0: diff.relative
+      GIT_CONFIG_VALUE_0: "true"
+      GIT_CONFIG_KEY_1: diff.noprefix
+      GIT_CONFIG_VALUE_1: "false"
+      GIT_CONFIG_KEY_2: diff.context
+      GIT_CONFIG_VALUE_2: "0"
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6.5.0
+        with:
+          go-version-file: pluginkit/go.mod
+          cache-dependency-path: pluginkit/go.mod
+      - id: changed
+        run: |
+          changed="$(git diff --merge-base --name-only --diff-filter=d "$BASE" -- . ':(exclude)graphwire' | awk '/\.go$/ && !/_test\.go$/')"
+          if [ -z "$changed" ]; then
+            echo "No Go source changed under pluginkit, so there is nothing to mutate."
+            echo "run=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          for file in $changed; do
+            test -f "$file" || { echo "The diff names $file, which gremlins cannot find from pluginkit."; exit 1; }
+          done
+          echo "run=true" >> "$GITHUB_OUTPUT"
+      - if: steps.changed.outputs.run == 'false'
+        run: |
+          ulimit -v 12582912
+          go run github.com/go-gremlins/gremlins/cmd/gremlins@v0.6.0 unleash --config .gremlins.yaml --dry-run .
+      - if: steps.changed.outputs.run == 'true'
+        run: |
+          ulimit -v 12582912
+          go run github.com/go-gremlins/gremlins/cmd/gremlins@v0.6.0 unleash --config .gremlins.yaml --diff "$BASE" -o gremlins.json .
+      - if: always() && steps.changed.outputs.run == 'true'
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: gremlins-report
+          path: pluginkit/gremlins.json
+          retention-days: 7
+          if-no-files-found: ignore

pluginkit/.gremlins.yaml

@@ -0,0 +1,10 @@
+unleash:
+  workers: 3
+  output-statuses: lct
+  exclude-files:
+    - '^graphwire/'
+mutants:
+  invert-logical:
+    enabled: true
+  invert-loopctrl:
+    enabled: true

pluginkit/CHANGELOG.md

@@ -6,6 +6,8 @@ Releases of this module are tagged `pluginkit/vX.Y.Z`. Releases up to
 ## Unreleased
 
 - The module needs Go 1.27.3.
+- `NewHostWithMigrationStore` returns a host whose `Migrate` and `Start` skip each plugin a `MigrationStore` records as current, by the version its `MigrationVersioner` reports.
+- An optional `MigratorOf` lookup gives that host the `Migrator` of a plugin that ships its schema as data.
 
 ## 0.7.0 - 2026-10-15
 

pluginkit/host.go

@@ -10,22 +10,50 @@ import (
 	"time"
 )
 
+var (
+	// errNoMigrationStore refuses a host built to skip migrations with no store to read them from.
+	errNoMigrationStore = errors.New("pluginkit: the migration store is nil")
+	// errEmptyMigrationVersion refuses a migration version that holds nothing to compare.
+	errEmptyMigrationVersion = errors.New("the version is empty")
+)
+
 // Host starts and stops a fixed set of plugins.
 type Host struct {
-	plugins []Plugin
+	plugins    []Plugin
+	store      MigrationStore
+	migratorOf MigratorOf
 }
 
 // NewHost returns a [Host] managing plugins. It panics when two
 // plugins share an ID.
 func NewHost(plugins ...Plugin) *Host {
+	if err := duplicateID(plugins); err != nil {
+		panic(err.Error())
+	}
+	return &Host{plugins: plugins}
+}
+
+// NewHostWithMigrationStore returns a [Host] whose Migrate skips every plugin store records as current.
+func NewHostWithMigrationStore(store MigrationStore, migratorOf MigratorOf, plugins ...Plugin) (*Host, error) {
+	if store == nil {
+		return nil, errNoMigrationStore
+	}
+	if err := duplicateID(plugins); err != nil {
+		return nil, err
+	}
+	return &Host{plugins: plugins, store: store, migratorOf: migratorOf}, nil
+}
+
+// duplicateID returns an error naming the first id two plugins share.
+func duplicateID(plugins []Plugin) error {
 	seen := make(map[string]struct{}, len(plugins))
 	for _, p := range plugins {
 		if _, ok := seen[p.ID()]; ok {
-			panic(fmt.Sprintf("pluginkit: duplicate id %q", p.ID()))
+			return fmt.Errorf("pluginkit: duplicate id %q", p.ID())
 		}
 		seen[p.ID()] = struct{}{}
 	}
-	return &Host{plugins: plugins}
+	return nil
 }
 
 // Start migrates and starts every plugin in order, stopping the started ones within stopGrace when one fails.
@@ -51,29 +79,106 @@ func (h *Host) rollBack(ctx context.Context, stopGrace time.Duration, index int)
 	return h.stopDownFrom(stopping, index)
 }
 
-// Migrate applies the schema of every [Migrator] plugin in registration order, stopping at the first failure.
+// Migrate applies the schema of every [Migrator] plugin in order, past those its store records as current.
 func (h *Host) Migrate(ctx context.Context) error {
+	if h.store == nil {
+		return h.migrateEvery(ctx)
+	}
+	versions, err := h.readVersions(ctx)
+	if err != nil {
+		return err
+	}
 	for _, p := range h.plugins {
-		migrator, ok := p.(Migrator)
-		if !ok {
-			continue
-		}
-		if err := safeCall(ctx, p.ID(), "migrate", migrator.Migrate); err != nil {
+		if err := h.migrateUnlessCurrent(ctx, p, versions); err != nil {
 			return err
 		}
 	}
 	return nil
 }
 
+// readVersions returns every migration version the store records, in one read.
+func (h *Host) readVersions(ctx context.Context) (map[string]string, error) {
+	var versions map[string]string
+	err := guarded(ctx, "read the migration versions", func(ctx context.Context) error {
+		var err error
+		versions, err = h.store.Versions(ctx)
+		return err
+	})
+	return versions, err
+}
+
+// migrateUnlessCurrent applies the schema of p unless versions holds its version, then records the one it applied.
+func (h *Host) migrateUnlessCurrent(ctx context.Context, p Plugin, versions map[string]string) error {
+	migrator, ok, err := h.migratorFor(ctx, p)
+	if err != nil || !ok {
+		return err
+	}
+	versioner, ok := migrator.(MigrationVersioner)
+	if !ok {
+		return safeCall(ctx, p.ID(), "migrate", migrator.Migrate)
+	}
+	version, err := migrationVersion(ctx, p.ID(), versioner)
+	if err != nil || version == versions[p.ID()] {
+		return err
+	}
+	if err := safeCall(ctx, p.ID(), "migrate", migrator.Migrate); err != nil {
+		return err
+	}
+	return safeCall(ctx, p.ID(), "record", func(ctx context.Context) error {
+		return h.store.Record(ctx, p.ID(), version)
+	})
+}
+
+// migratorFor returns the [Migrator] the lookup gives for p, or p itself when the lookup gives none.
+func (h *Host) migratorFor(ctx context.Context, p Plugin) (migrator Migrator, ok bool, err error) {
+	if h.migratorOf != nil {
+		err = safeCall(ctx, p.ID(), "migrator lookup", func(context.Context) error {
+			migrator, ok = h.migratorOf(p)
+			return nil
+		})
+		if err != nil || ok {
+			return migrator, ok, err
+		}
+	}
+	migrator, ok = p.(Migrator)
+	return migrator, ok, nil
+}
+
+// migrationVersion returns the migration version versioner reports for the plugin id, refusing an empty one.
+func migrationVersion(ctx context.Context, id string, versioner MigrationVersioner) (string, error) {
+	var version string
+	err := safeCall(ctx, id, "migration version", func(context.Context) error {
+		var err error
+		if version, err = versioner.MigrationVersion(); err == nil && version == "" {
+			err = errEmptyMigrationVersion
+		}
+		return err
+	})
+	return version, err
+}
+
+// migrateEvery applies the schema of every [Migrator] plugin in registration order, stopping at the first failure.
+func (h *Host) migrateEvery(ctx context.Context) error {
+	return callEach(ctx, h.plugins, "migrate", Migrator.Migrate)
+}
+
 // Seed asks every [Seeder] plugin to fill its schema in registration order,
 // stopping at the first failure.
 func (h *Host) Seed(ctx context.Context) error {
-	for _, p := range h.plugins {
-		seeder, ok := p.(Seeder)
+	return callEach(ctx, h.plugins, "seed", Seeder.Seed)
+}
+
+// callEach calls step on every plugin that is a T, in registration order, stopping at the first failure.
+func callEach[T any](
+	ctx context.Context, plugins []Plugin, operation string, step func(T, context.Context) error,
+) error {
+	for _, p := range plugins {
+		capable, ok := p.(T)
 		if !ok {
 			continue
 		}
-		if err := safeCall(ctx, p.ID(), "seed", seeder.Seed); err != nil {
+		call := func(ctx context.Context) error { return step(capable, ctx) }
+		if err := safeCall(ctx, p.ID(), operation, call); err != nil {
 			return err
 		}
 	}
@@ -123,14 +228,19 @@ func (h *Host) stopDownFrom(ctx context.Context, index int) error {
 
 // safeCall runs fn, wrapping any returned error and converting any panic into an error tagged with the
 // plugin id and operation.
-func safeCall(ctx context.Context, id, operation string, fn func(context.Context) error) (err error) {
+func safeCall(ctx context.Context, id, operation string, fn func(context.Context) error) error {
+	return guarded(ctx, id+" "+operation, fn)
+}
+
+// guarded runs fn, wrapping any returned error and converting any panic into an error tagged with name.
+func guarded(ctx context.Context, name string, fn func(context.Context) error) (err error) {
 	defer func() {
 		if recovered := recover(); recovered != nil {
-			err = fmt.Errorf("pluginkit: %s %s panicked: %v", id, operation, recovered)
+			err = fmt.Errorf("pluginkit: %s panicked: %v", name, recovered)
 		}
 	}()
 	if err := fn(ctx); err != nil {
-		return fmt.Errorf("pluginkit: %s %s: %w", id, operation, err)
+		return fmt.Errorf("pluginkit: %s: %w", name, err)
 	}
 	return nil
 }

pluginkit/pluginkit.go

@@ -18,12 +18,29 @@ type Plugin interface {
 	Stop(ctx context.Context) error
 }
 
-// Migrator is implemented by plugins that own database schema, which
-// the host migrates before starting any plugin.
+// Migrator is implemented by plugins that own database schema, which a host migrates before starting any
+// plugin, and which a host with a [MigrationStore] skips while its recorded version is current.
 type Migrator interface {
 	Migrate(ctx context.Context) error
 }
 
+// MigrationVersioner is implemented by a [Migrator] whose schema reports a version a host can compare.
+type MigrationVersioner interface {
+	// MigrationVersion returns the version of the schema, which a host compares as an opaque string.
+	MigrationVersion() (string, error)
+}
+
+// MigrationStore is an application's record of the migration version each plugin last applied.
+type MigrationStore interface {
+	// Versions returns every recorded version, keyed by plugin id, in one read.
+	Versions(ctx context.Context) (map[string]string, error)
+	// Record stores version as the one plugin id has now applied.
+	Record(ctx context.Context, id, version string) error
+}
+
+// MigratorOf returns the [Migrator] that applies a plugin's schema for it, and false when the plugin's own applies.
+type MigratorOf func(Plugin) (Migrator, bool)
+
 // Seeder is implemented by plugins that can fill their own schema with
 // development data, which the host asks for outside the start path.
 type Seeder interface {