From 85e94945930ccb4d24acdcf199148c90516f82f3 Mon Sep 17 00:00:00 2001
From: Thomas Honeyman <hello@thomashoneyman.com>
Date: Wed, 22 Jul 2026 19:57:16 +0000
Subject: [PATCH 1/8] Split registry read and write effects

Amp-Thread-ID: https://ampcode.com/threads/T-019f8b54-076c-701a-863f-75106cd6f5bd

Co-authored-by: Thomas Honeyman <admin@thomashoneyman.com>
---
 app-e2e/src/Test/E2E/Scripts.purs     |   6 +-
 app/src/App/API.purs                  |   6 +-
 app/src/App/Effect/PackageSets.purs   |   6 +-
 app/src/App/Effect/Registry.purs      | 143 +++++++++++++++-----------
 app/src/App/Server/Env.purs           |  22 ++--
 app/src/App/Server/JobExecutor.purs   |   4 +-
 app/src/App/Server/MatrixBuilder.purs |  10 +-
 app/test/App/API.purs                 |   2 +-
 app/test/App/Effect/Registry.purs     |  10 +-
 app/test/Test/Assert/Run.purs         |  62 ++++++-----
 scripts/src/DailyImporter.purs        |   6 +-
 scripts/src/PackageSetUpdater.purs    |   6 +-
 scripts/src/PackageTransferrer.purs   |   6 +-
 scripts/src/VerifyIntegrity.purs      |   4 +-
 14 files changed, 165 insertions(+), 128 deletions(-)

diff --git a/app-e2e/src/Test/E2E/Scripts.purs b/app-e2e/src/Test/E2E/Scripts.purs
index 69d8f6be..72a05661 100644
--- a/app-e2e/src/Test/E2E/Scripts.purs
+++ b/app-e2e/src/Test/E2E/Scripts.purs
@@ -191,7 +191,7 @@ runDailyImporterScript = do
   result <- liftAff
     $ DailyImporter.runDailyImport DailyImporter.Submit resourceEnv.registryApiUrl
     # Except.runExcept
-    # Registry.interpret (Registry.handle registryEnv)
+    # Registry.interpretRead (Registry.handleRead registryEnv)
     # GitHub.interpret (GitHub.handle { octokit, cache, ref: githubCacheRef })
     # Log.interpret (Log.handleTerminal Quiet)
     # Env.runResourceEnv resourceEnv
@@ -207,7 +207,7 @@ runPackageTransferrerScript = do
   result <- liftAff
     $ PackageTransferrer.runPackageTransferrer PackageTransferrer.Submit (Just privateKey) resourceEnv.registryApiUrl
     # Except.runExcept
-    # Registry.interpret (Registry.handle registryEnv)
+    # Registry.interpretRead (Registry.handleRead registryEnv)
     # GitHub.interpret (GitHub.handle { octokit, cache, ref: githubCacheRef })
     # Log.interpret (Log.handleTerminal Quiet)
     # Env.runResourceEnv resourceEnv
@@ -223,7 +223,7 @@ runPackageSetUpdaterScript = do
   result <- liftAff
     $ PackageSetUpdater.runPackageSetUpdater PackageSetUpdater.Submit resourceEnv.registryApiUrl
     # Except.runExcept
-    # Registry.interpret (Registry.handle registryEnv)
+    # Registry.interpretRead (Registry.handleRead registryEnv)
     # GitHub.interpret (GitHub.handle { octokit, cache, ref: githubCacheRef })
     # Log.interpret (Log.handleTerminal Quiet)
     # Env.runResourceEnv resourceEnv
diff --git a/app/src/App/API.purs b/app/src/App/API.purs
index d8d80e77..a4b69c5d 100644
--- a/app/src/App/API.purs
+++ b/app/src/App/API.purs
@@ -76,7 +76,7 @@ import Registry.App.Effect.PackageSets (Change(..), PACKAGE_SETS)
 import Registry.App.Effect.PackageSets as PackageSets
 import Registry.App.Effect.Pursuit (PURSUIT)
 import Registry.App.Effect.Pursuit as Pursuit
-import Registry.App.Effect.Registry (REGISTRY)
+import Registry.App.Effect.Registry (REGISTRY, REGISTRY_READ)
 import Registry.App.Effect.Registry as ManifestIndex
 import Registry.App.Effect.Registry as Registry
 import Registry.App.Effect.Source (SOURCE)
@@ -349,7 +349,7 @@ resolveCompilerAndDeps
   -> Manifest
   -> Maybe Version -- payload.compiler
   -> Maybe (Map PackageName Version) -- payload.resolutions
-  -> Run (REGISTRY + LOG + AFF + EXCEPT String + r) { compiler :: Version, resolutions :: Map PackageName Version }
+  -> Run (LOG + AFF + EXCEPT String + r) { compiler :: Version, resolutions :: Map PackageName Version }
 resolveCompilerAndDeps compilerIndex manifest@(Manifest { dependencies }) maybeCompiler maybeResolutions = do
   Log.debug "Resolving compiler and dependencies..."
   case maybeCompiler of
@@ -1067,7 +1067,7 @@ type FindAllCompilersResult =
 findAllCompilers
   :: forall r
    . { source :: FilePath, manifest :: Manifest, compilers :: NonEmptyArray Version }
-  -> Run (REGISTRY + STORAGE + COMPILER_CACHE + LOG + AFF + EFFECT + EXCEPT String + r) FindAllCompilersResult
+  -> Run (REGISTRY_READ + STORAGE + COMPILER_CACHE + LOG + AFF + EFFECT + EXCEPT String + r) FindAllCompilersResult
 findAllCompilers { source, manifest, compilers } = do
   compilerIndex <- MatrixBuilder.readCompilerIndex
   checkedCompilers <- for compilers \target -> do
diff --git a/app/src/App/Effect/PackageSets.purs b/app/src/App/Effect/PackageSets.purs
index f50f7344..9309f248 100644
--- a/app/src/App/Effect/PackageSets.purs
+++ b/app/src/App/Effect/PackageSets.purs
@@ -24,7 +24,7 @@ import Registry.App.CLI.Purs as Purs
 import Registry.App.CLI.Tar as Tar
 import Registry.App.Effect.Log (LOG)
 import Registry.App.Effect.Log as Log
-import Registry.App.Effect.Registry (REGISTRY)
+import Registry.App.Effect.Registry (REGISTRY_READ)
 import Registry.App.Effect.Registry as Registry
 import Registry.App.Effect.Storage (STORAGE)
 import Registry.App.Effect.Storage as Storage
@@ -86,7 +86,7 @@ type PackageSetsEnv =
 
 -- | A handler for the PACKAGE_SETS effect which compiles the package sets and
 -- | returns the results.
-handle :: forall r a. PackageSetsEnv -> PackageSets a -> Run (REGISTRY + STORAGE + LOG + AFF + EFFECT + r) a
+handle :: forall r a. PackageSetsEnv -> PackageSets a -> Run (REGISTRY_READ + STORAGE + LOG + AFF + EFFECT + r) a
 handle env = case _ of
   UpgradeAtomic oldSet@(PackageSet { packages }) compiler changes reply -> reply <$> Except.runExcept do
     Log.info $ "Performing atomic upgrade of package set " <> Version.print (un PackageSet oldSet).version
@@ -423,7 +423,7 @@ type ValidatedCandidates =
   }
 
 -- | Validate a package set is self-contained, ignoring version bounds.
-validatePackageSet :: forall r. PackageSet -> Run (REGISTRY + LOG + EXCEPT String + r) Unit
+validatePackageSet :: forall r. PackageSet -> Run (REGISTRY_READ + LOG + EXCEPT String + r) Unit
 validatePackageSet (PackageSet set) = do
   Log.debug $ "Validating package set version " <> Version.print set.version
   index <- Registry.readAllManifests
diff --git a/app/src/App/Effect/Registry.purs b/app/src/App/Effect/Registry.purs
index d3c0acb9..7ea05e47 100644
--- a/app/src/App/Effect/Registry.purs
+++ b/app/src/App/Effect/Registry.purs
@@ -68,74 +68,91 @@ type REGISTRY_CACHE r = (registryCache :: Cache RegistryCache | r)
 _registryCache :: Proxy "registryCache"
 _registryCache = Proxy
 
-data Registry a
+data RegistryRead a
   = ReadManifest PackageName Version (Either String (Maybe Manifest) -> a)
-  | WriteManifest Manifest (Either String Unit -> a)
-  | DeleteManifest PackageName Version (Either String Unit -> a)
   | ReadAllManifests (Either String ManifestIndex -> a)
   | ReadMetadata PackageName (Either String (Maybe Metadata) -> a)
-  | WriteMetadata PackageName Metadata (Either String Unit -> a)
   | ReadAllMetadata (Either String (Map PackageName Metadata) -> a)
   | ReadLatestPackageSet (Either String (Maybe PackageSet) -> a)
-  | WritePackageSet PackageSet String (Either String Unit -> a)
   | ReadAllPackageSets (Either String (Map Version PackageSet) -> a)
+
+derive instance Functor RegistryRead
+
+data RegistryWrite a
+  = WriteManifest Manifest (Either String Unit -> a)
+  | DeleteManifest PackageName Version (Either String Unit -> a)
+  | WriteMetadata PackageName Metadata (Either String Unit -> a)
+  | WritePackageSet PackageSet String (Either String Unit -> a)
   | MirrorPackageSet PackageSet (Either String Unit -> a)
 
-derive instance Functor Registry
+derive instance Functor RegistryWrite
+
+-- | An effect for reading registry resources, like manifests, metadata, and
+-- | package sets.
+type REGISTRY_READ r = (registryRead :: RegistryRead | r)
+
+_registryRead :: Proxy "registryRead"
+_registryRead = Proxy
+
+-- | An effect for writing registry resources, like manifests, metadata, and
+-- | package sets.
+type REGISTRY_WRITE r = (registryWrite :: RegistryWrite | r)
 
--- | An effect for interacting with registry resources, like manifests, metadata,
--- | and the package sets.
-type REGISTRY r = (registry :: Registry | r)
+_registryWrite :: Proxy "registryWrite"
+_registryWrite = Proxy
 
-_registry :: Proxy "registry"
-_registry = Proxy
+-- | An effect for reading and writing registry resources.
+type REGISTRY r = (REGISTRY_READ + REGISTRY_WRITE + r)
 
 -- | Read a manifest from the manifest index
-readManifest :: forall r. PackageName -> Version -> Run (REGISTRY + EXCEPT String + r) (Maybe Manifest)
-readManifest name version = Except.rethrow =<< Run.lift _registry (ReadManifest name version identity)
+readManifest :: forall r. PackageName -> Version -> Run (REGISTRY_READ + EXCEPT String + r) (Maybe Manifest)
+readManifest name version = Except.rethrow =<< Run.lift _registryRead (ReadManifest name version identity)
 
 -- | Write a manifest to the manifest index
-writeManifest :: forall r. Manifest -> Run (REGISTRY + EXCEPT String + r) Unit
-writeManifest manifest = Except.rethrow =<< Run.lift _registry (WriteManifest manifest identity)
+writeManifest :: forall r. Manifest -> Run (REGISTRY_WRITE + EXCEPT String + r) Unit
+writeManifest manifest = Except.rethrow =<< Run.lift _registryWrite (WriteManifest manifest identity)
 
 -- | Delete a manifest from the manifest index
-deleteManifest :: forall r. PackageName -> Version -> Run (REGISTRY + EXCEPT String + r) Unit
-deleteManifest name version = Except.rethrow =<< Run.lift _registry (DeleteManifest name version identity)
+deleteManifest :: forall r. PackageName -> Version -> Run (REGISTRY_WRITE + EXCEPT String + r) Unit
+deleteManifest name version = Except.rethrow =<< Run.lift _registryWrite (DeleteManifest name version identity)
 
 -- | Read the entire manifest index
-readAllManifests :: forall r. Run (REGISTRY + EXCEPT String + r) ManifestIndex
-readAllManifests = Except.rethrow =<< Run.lift _registry (ReadAllManifests identity)
+readAllManifests :: forall r. Run (REGISTRY_READ + EXCEPT String + r) ManifestIndex
+readAllManifests = Except.rethrow =<< Run.lift _registryRead (ReadAllManifests identity)
 
 -- | Read the registry metadata for a package
-readMetadata :: forall r. PackageName -> Run (REGISTRY + EXCEPT String + r) (Maybe Metadata)
-readMetadata name = Except.rethrow =<< Run.lift _registry (ReadMetadata name identity)
+readMetadata :: forall r. PackageName -> Run (REGISTRY_READ + EXCEPT String + r) (Maybe Metadata)
+readMetadata name = Except.rethrow =<< Run.lift _registryRead (ReadMetadata name identity)
 
 -- | Write the registry metadata for a package
-writeMetadata :: forall r. PackageName -> Metadata -> Run (REGISTRY + EXCEPT String + r) Unit
-writeMetadata name metadata = Except.rethrow =<< Run.lift _registry (WriteMetadata name metadata identity)
+writeMetadata :: forall r. PackageName -> Metadata -> Run (REGISTRY_WRITE + EXCEPT String + r) Unit
+writeMetadata name metadata = Except.rethrow =<< Run.lift _registryWrite (WriteMetadata name metadata identity)
 
 -- | Read the registry metadata for all packages
-readAllMetadata :: forall r. Run (REGISTRY + EXCEPT String + r) (Map PackageName Metadata)
-readAllMetadata = Except.rethrow =<< Run.lift _registry (ReadAllMetadata identity)
+readAllMetadata :: forall r. Run (REGISTRY_READ + EXCEPT String + r) (Map PackageName Metadata)
+readAllMetadata = Except.rethrow =<< Run.lift _registryRead (ReadAllMetadata identity)
 
 -- | Read the latest package set from the registry
-readLatestPackageSet :: forall r. Run (REGISTRY + EXCEPT String + r) (Maybe PackageSet)
-readLatestPackageSet = Except.rethrow =<< Run.lift _registry (ReadLatestPackageSet identity)
+readLatestPackageSet :: forall r. Run (REGISTRY_READ + EXCEPT String + r) (Maybe PackageSet)
+readLatestPackageSet = Except.rethrow =<< Run.lift _registryRead (ReadLatestPackageSet identity)
 
 -- | Write a package set to the registry
-writePackageSet :: forall r. PackageSet -> String -> Run (REGISTRY + EXCEPT String + r) Unit
-writePackageSet set message = Except.rethrow =<< Run.lift _registry (WritePackageSet set message identity)
+writePackageSet :: forall r. PackageSet -> String -> Run (REGISTRY_WRITE + EXCEPT String + r) Unit
+writePackageSet set message = Except.rethrow =<< Run.lift _registryWrite (WritePackageSet set message identity)
 
 -- | Read all package sets from the registry
-readAllPackageSets :: forall r. Run (REGISTRY + EXCEPT String + r) (Map Version PackageSet)
-readAllPackageSets = Except.rethrow =<< Run.lift _registry (ReadAllPackageSets identity)
+readAllPackageSets :: forall r. Run (REGISTRY_READ + EXCEPT String + r) (Map Version PackageSet)
+readAllPackageSets = Except.rethrow =<< Run.lift _registryRead (ReadAllPackageSets identity)
 
 -- | Mirror a package set to the legacy package-sets repo
-mirrorPackageSet :: forall r. PackageSet -> Run (REGISTRY + EXCEPT String + r) Unit
-mirrorPackageSet set = Except.rethrow =<< Run.lift _registry (MirrorPackageSet set identity)
+mirrorPackageSet :: forall r. PackageSet -> Run (REGISTRY_WRITE + EXCEPT String + r) Unit
+mirrorPackageSet set = Except.rethrow =<< Run.lift _registryWrite (MirrorPackageSet set identity)
 
-interpret :: forall r a. (Registry ~> Run r) -> Run (REGISTRY + r) a -> Run r a
-interpret handler = Run.interpret (Run.on _registry handler Run.send)
+interpretRead :: forall r a. (RegistryRead ~> Run r) -> Run (REGISTRY_READ + r) a -> Run r a
+interpretRead handler = Run.interpret (Run.on _registryRead handler Run.send)
+
+interpretWrite :: forall r a. (RegistryWrite ~> Run r) -> Run (REGISTRY_WRITE + r) a -> Run r a
+interpretWrite handler = Run.interpret (Run.on _registryWrite handler Run.send)
 
 -- | A legend for repositories that can be fetched and committed to.
 data RepoKey
@@ -213,18 +230,28 @@ defaultRepos =
   , legacyPackageSets: Legacy.PackageSet.legacyPackageSetsRepo
   }
 
--- | Handle the REGISTRY effect by downloading the registry and registry-index
--- | repositories locally and reading and writing their contents from disk.
+data RegistryOperation a
+  = ReadOperation (RegistryRead a)
+  | WriteOperation (RegistryWrite a)
+
+-- | Handle the REGISTRY_READ effect by downloading the registry and
+-- | registry-index repositories locally and reading their contents from disk.
+handleRead :: forall r a. RegistryEnv -> RegistryRead a -> Run (GITHUB + LOG + AFF + EFFECT + r) a
+handleRead env = handleOperation env <<< ReadOperation
+
+-- | Handle the REGISTRY_WRITE effect by writing registry resources to disk.
 -- | Writes can optionally commit and push to the upstream Git repository.
--- |
--- | This handler enforces a memory-only cache: we do not want to cache on the
--- | file system or other storage because this handler relies on the registry
--- | Git repositories instead.
-handle :: forall r a. RegistryEnv -> Registry a -> Run (GITHUB + LOG + AFF + EFFECT + r) a
-handle env = Cache.interpret _registryCache (Cache.handleMemory env.cacheRef) <<< case _ of
-  ReadManifest name version reply -> do
+handleWrite :: forall r a. RegistryEnv -> RegistryWrite a -> Run (GITHUB + LOG + AFF + EFFECT + r) a
+handleWrite env = handleOperation env <<< WriteOperation
+
+-- | These handlers share a memory-only cache: we do not want to cache on the
+-- | file system or other storage because they rely on the registry Git
+-- | repositories instead.
+handleOperation :: forall r a. RegistryEnv -> RegistryOperation a -> Run (GITHUB + LOG + AFF + EFFECT + r) a
+handleOperation env = Cache.interpret _registryCache (Cache.handleMemory env.cacheRef) <<< case _ of
+  ReadOperation (ReadManifest name version reply) -> do
     let formatted = formatPackageVersion name version
-    handle env (ReadAllManifests identity) >>= case _ of
+    handleOperation env (ReadOperation (ReadAllManifests identity)) >>= case _ of
       Left error -> pure $ reply $ Left error
       Right index -> case ManifestIndex.lookup name version index of
         Nothing -> do
@@ -233,10 +260,10 @@ handle env = Cache.interpret _registryCache (Cache.handleMemory env.cacheRef) <<
         Just manifest -> do
           pure $ reply $ Right $ Just manifest
 
-  WriteManifest manifest@(Manifest { name, version }) reply -> map (map reply) Except.runExcept do
+  WriteOperation (WriteManifest manifest@(Manifest { name, version }) reply) -> map (map reply) Except.runExcept do
     let formatted = formatPackageVersion name version
     Log.info $ "Writing manifest for " <> formatted <> ":\n" <> printJson Manifest.codec manifest
-    index <- Except.rethrow =<< handle env (ReadAllManifests identity)
+    index <- Except.rethrow =<< handleOperation env (ReadOperation (ReadAllManifests identity))
     case ManifestIndex.insert ManifestIndex.ConsiderRanges manifest index of
       Left error ->
         Except.throw $ Array.fold
@@ -256,10 +283,10 @@ handle env = Cache.interpret _registryCache (Cache.handleMemory env.cacheRef) <<
               Git.Changed -> Log.info "Wrote and committed manifest."
             Cache.put _registryCache AllManifests updated
 
-  DeleteManifest name version reply -> map (map reply) Except.runExcept do
+  WriteOperation (DeleteManifest name version reply) -> map (map reply) Except.runExcept do
     let formatted = formatPackageVersion name version
     Log.info $ "Deleting manifest for " <> formatted
-    index <- Except.rethrow =<< handle env (ReadAllManifests identity)
+    index <- Except.rethrow =<< handleOperation env (ReadOperation (ReadAllManifests identity))
     case ManifestIndex.delete ManifestIndex.ConsiderRanges name version index of
       Left error ->
         Except.throw $ Array.fold
@@ -281,7 +308,7 @@ handle env = Cache.interpret _registryCache (Cache.handleMemory env.cacheRef) <<
                 Log.info "Wrote and committed manifest."
             Cache.put _registryCache AllManifests updated
 
-  ReadAllManifests reply -> map (map reply) Except.runExcept do
+  ReadOperation (ReadAllManifests reply) -> map (map reply) Except.runExcept do
     let
       refreshIndex = do
         let indexPath = repoPath ManifestIndexRepo
@@ -303,7 +330,7 @@ handle env = Cache.interpret _registryCache (Cache.handleMemory env.cacheRef) <<
         Log.info "Manifest index has changed, replacing cache..."
         refreshIndex
 
-  ReadMetadata name reply -> map (map reply) Except.runExcept do
+  ReadOperation (ReadMetadata name reply) -> map (map reply) Except.runExcept do
     let printedName = PackageName.print name
     let dir = repoPath RegistryRepo
 
@@ -363,7 +390,7 @@ handle env = Cache.interpret _registryCache (Cache.handleMemory env.cacheRef) <<
         Cache.delete _registryCache AllMetadata
         readMetadataFromDisk
 
-  WriteMetadata name metadata reply -> map (map reply) Except.runExcept do
+  WriteOperation (WriteMetadata name metadata reply) -> map (map reply) Except.runExcept do
     let printedName = PackageName.print name
     Log.info $ "Writing metadata for " <> printedName
     Log.debug $ printJson Metadata.codec metadata
@@ -384,7 +411,7 @@ handle env = Cache.interpret _registryCache (Cache.handleMemory env.cacheRef) <<
         for_ cache \cached ->
           Cache.put _registryCache AllMetadata (Map.insert name metadata cached)
 
-  ReadAllMetadata reply -> map (map reply) Except.runExcept do
+  ReadOperation (ReadAllMetadata reply) -> map (map reply) Except.runExcept do
     let
       refreshMetadata = do
         let dir = repoPath RegistryRepo
@@ -408,7 +435,7 @@ handle env = Cache.interpret _registryCache (Cache.handleMemory env.cacheRef) <<
         Log.info "Registry repo has changed, replacing metadata cache..."
         refreshMetadata
 
-  ReadLatestPackageSet reply -> map (map reply) Except.runExcept do
+  ReadOperation (ReadLatestPackageSet reply) -> map (map reply) Except.runExcept do
     pull RegistryRepo >>= case _ of
       Left error -> Except.throw $ "Could not read package sets because the registry repo could not be checked: " <> error
       Right _ -> pure unit
@@ -429,7 +456,7 @@ handle env = Cache.interpret _registryCache (Cache.handleMemory env.cacheRef) <<
             Log.debug $ "Successfully read package set " <> printed
             pure $ Just set
 
-  WritePackageSet set@(PackageSet { version }) message reply -> map (map reply) Except.runExcept do
+  WriteOperation (WritePackageSet set@(PackageSet { version }) message reply) -> map (map reply) Except.runExcept do
     pull RegistryRepo >>= case _ of
       Left error -> Except.throw $ "Could not read package sets because the registry repo could not be checked: " <> error
       Right _ -> pure unit
@@ -445,7 +472,7 @@ handle env = Cache.interpret _registryCache (Cache.handleMemory env.cacheRef) <<
       Right Git.NoChange -> Log.info "Did not commit package set because it was unchanged."
       Right Git.Changed -> Log.info "Wrote and committed package set."
 
-  ReadAllPackageSets reply -> map (map reply) Except.runExcept do
+  ReadOperation (ReadAllPackageSets reply) -> map (map reply) Except.runExcept do
     pull RegistryRepo >>= case _ of
       Left error -> Except.throw $ "Could not read package sets because the registry repo could not be checked: " <> error
       Right _ -> pure unit
@@ -469,11 +496,11 @@ handle env = Cache.interpret _registryCache (Cache.handleMemory env.cacheRef) <<
 
   -- https://github.com/purescript/package-sets/blob/psc-0.15.4-20220829/release.sh
   -- https://github.com/purescript/package-sets/blob/psc-0.15.4-20220829/update-latest-compatible-sets.sh
-  MirrorPackageSet set@(PackageSet { version }) reply -> map (map reply) Except.runExcept do
+  WriteOperation (MirrorPackageSet set@(PackageSet { version }) reply) -> map (map reply) Except.runExcept do
     let name = Version.print version
     Log.info $ "Mirroring legacy package set " <> name <> " to the legacy package sets repo"
 
-    manifests <- Except.rethrow =<< handle env (ReadAllManifests identity)
+    manifests <- Except.rethrow =<< handleOperation env (ReadOperation (ReadAllManifests identity))
 
     Log.debug $ "Converting package set..."
     converted <- case Legacy.PackageSet.convertPackageSet manifests set of
diff --git a/app/src/App/Server/Env.purs b/app/src/App/Server/Env.purs
index 5c0ddb39..b2310614 100644
--- a/app/src/App/Server/Env.purs
+++ b/app/src/App/Server/Env.purs
@@ -147,19 +147,19 @@ runEffects env operation = Aff.attempt do
     writeMode
       | env.vars.readOnly = Registry.ReadOnly
       | otherwise = Registry.CommitAs (Git.pacchettibottiCommitter env.vars.token)
+    registryEnv =
+      { jobId: env.jobId
+      , repos: Registry.defaultRepos
+      , pull: Git.ForceClean
+      , write: writeMode
+      , workdir: scratchDir
+      , debouncer: env.debouncer
+      , cacheRef: env.registryCacheRef
+      }
   operation
     # PackageSets.interpret (PackageSets.handle { workdir: scratchDir })
-    # Registry.interpret
-        ( Registry.handle
-            { jobId: env.jobId
-            , repos: Registry.defaultRepos
-            , pull: Git.ForceClean
-            , write: writeMode
-            , workdir: scratchDir
-            , debouncer: env.debouncer
-            , cacheRef: env.registryCacheRef
-            }
-        )
+    # Registry.interpretWrite (Registry.handleWrite registryEnv)
+    # Registry.interpretRead (Registry.handleRead registryEnv)
     # Pursuit.interpret (if env.vars.readOnly then Pursuit.handlePure else Pursuit.handleAff env.vars.token)
     # Storage.interpret (if env.vars.readOnly then Storage.handleReadOnly env.cacheDir else Storage.handleS3 { s3: { key: env.vars.spacesKey, secret: env.vars.spacesSecret }, cache: env.cacheDir })
     # Source.interpret Source.handle
diff --git a/app/src/App/Server/JobExecutor.purs b/app/src/App/Server/JobExecutor.purs
index 8bcd8d63..fe505cd1 100644
--- a/app/src/App/Server/JobExecutor.purs
+++ b/app/src/App/Server/JobExecutor.purs
@@ -21,7 +21,7 @@ import Registry.App.Effect.Db (DB)
 import Registry.App.Effect.Db as Db
 import Registry.App.Effect.Log (LOG)
 import Registry.App.Effect.Log as Log
-import Registry.App.Effect.Registry (REGISTRY)
+import Registry.App.Effect.Registry (REGISTRY_READ)
 import Registry.App.Effect.Registry as Registry
 import Registry.App.Server.Env (ServerEffects, ServerEnv, runEffects)
 import Registry.App.Server.MatrixBuilder as MatrixBuilder
@@ -186,7 +186,7 @@ executeJob _ = case _ of
         }
   PackageSetJob payload -> API.packageSetUpdate payload
 
-upgradeRegistryToNewCompiler :: forall r. Version -> Run (DB + LOG + EXCEPT String + REGISTRY + r) Unit
+upgradeRegistryToNewCompiler :: forall r. Version -> Run (DB + LOG + EXCEPT String + REGISTRY_READ + r) Unit
 upgradeRegistryToNewCompiler newCompilerVersion = do
   Log.info $ "New compiler found: " <> Version.print newCompilerVersion
   Log.info "Starting upgrade of the whole registry to the new compiler..."
diff --git a/app/src/App/Server/MatrixBuilder.purs b/app/src/App/Server/MatrixBuilder.purs
index 73941d59..6e1ebc00 100644
--- a/app/src/App/Server/MatrixBuilder.purs
+++ b/app/src/App/Server/MatrixBuilder.purs
@@ -30,7 +30,7 @@ import Registry.App.CLI.PursVersions as PursVersions
 import Registry.App.CLI.Tar as Tar
 import Registry.App.Effect.Log (LOG)
 import Registry.App.Effect.Log as Log
-import Registry.App.Effect.Registry (REGISTRY)
+import Registry.App.Effect.Registry (REGISTRY, REGISTRY_READ)
 import Registry.App.Effect.Registry as Registry
 import Registry.App.Effect.Storage (STORAGE)
 import Registry.App.Effect.Storage as Storage
@@ -102,7 +102,7 @@ runMatrixJob { compilerVersion, packageName, packageVersion, payload: buildPlan
 
 -- TODO feels like we should be doing this at startup and use the cache instead
 -- of reading files all over again
-readCompilerIndex :: forall r. Run (REGISTRY + AFF + EXCEPT String + r) Solver.CompilerIndex
+readCompilerIndex :: forall r. Run (REGISTRY_READ + AFF + EXCEPT String + r) Solver.CompilerIndex
 readCompilerIndex = do
   metadata <- Registry.readAllMetadata
   manifests <- Registry.readAllManifests
@@ -137,7 +137,7 @@ installBuildPlan resolutions dependenciesDir = do
 
 -- | Convert resolutions (Map PackageName Version) to build plan entries using metadata.
 -- | Fetches metadata for each package as needed.
-resolutionsToBuildPlan :: forall r. Map PackageName Version -> Run (REGISTRY + EXCEPT String + r) (Map PackageName BuildPlanEntry)
+resolutionsToBuildPlan :: forall r. Map PackageName Version -> Run (REGISTRY_READ + EXCEPT String + r) (Map PackageName BuildPlanEntry)
 resolutionsToBuildPlan resolutions =
   forWithIndex resolutions \name version -> do
     maybeMetadata <- Registry.readMetadata name
@@ -190,7 +190,7 @@ solveForAllCompilers solverData@{ compiler } = do
     trySolveForCompiler (solverData { compiler = target })
   pure $ Set.fromFoldable $ Array.catMaybes newJobs
 
-solveDependantsForCompiler :: forall r. MatrixSolverData -> Run (EXCEPT String + LOG + REGISTRY + r) (Set MatrixSolverResult)
+solveDependantsForCompiler :: forall r. MatrixSolverData -> Run (EXCEPT String + LOG + REGISTRY_READ + r) (Set MatrixSolverResult)
 solveDependantsForCompiler { compilerIndex, name, version, compiler } = do
   manifestIndex <- Registry.readAllManifests
   let seed = Tuple name version
@@ -276,7 +276,7 @@ trySolveForCompiler { compilerIndex, compiler, name, version, dependencies } = d
             ]
           pure Nothing
 
-checkIfNewCompiler :: forall r. Run (EXCEPT String + LOG + REGISTRY + AFF + r) (Maybe Version)
+checkIfNewCompiler :: forall r. Run (EXCEPT String + LOG + REGISTRY_READ + AFF + r) (Maybe Version)
 checkIfNewCompiler = do
   Log.info "Checking if there's a new compiler in town..."
   latestCompiler <- NonEmptyArray.foldr1 max <$> PursVersions.pursVersions
diff --git a/app/test/App/API.purs b/app/test/App/API.purs
index 0db7135d..0ecd69fd 100644
--- a/app/test/App/API.purs
+++ b/app/test/App/API.purs
@@ -78,7 +78,7 @@ assertPublicationState
    . PackageName
   -> Version
   -> { manifest :: Boolean, metadata :: Boolean, storage :: Boolean }
-  -> Run (Registry.REGISTRY + Storage.STORAGE + Except.EXCEPT String + r) Unit
+  -> Run (Registry.REGISTRY_READ + Storage.STORAGE + Except.EXCEPT String + r) Unit
 assertPublicationState name version expected = do
   storedVersions <- Storage.query name
   maybeMetadata <- Registry.readMetadata name
diff --git a/app/test/App/Effect/Registry.purs b/app/test/App/Effect/Registry.purs
index 241ab9af..e9f2f7f0 100644
--- a/app/test/App/Effect/Registry.purs
+++ b/app/test/App/Effect/Registry.purs
@@ -13,7 +13,7 @@ import Registry.App.Effect.GitHub (GITHUB, GitHub)
 import Registry.App.Effect.GitHub as GitHub
 import Registry.App.Effect.Log (LOG, Log(..))
 import Registry.App.Effect.Log as Log
-import Registry.App.Effect.Registry (REGISTRY, RegistryEnv, WriteMode(..))
+import Registry.App.Effect.Registry (REGISTRY_READ, RegistryEnv, WriteMode(..))
 import Registry.App.Effect.Registry as Registry
 import Registry.Foreign.FSExtra as FS.Extra
 import Registry.Foreign.Tmp as Tmp
@@ -36,7 +36,7 @@ spec = do
     Registry.appendJobIdToCommitMessage (Just (JobId "job-123")) message `Assert.shouldEqual`
       "Update metadata for prelude\n\nJob ID: job-123"
 
-  -- This test exercises the Registry.handle to verify that readMetadata does
+  -- This test exercises Registry.handleRead to verify that readMetadata does
   -- not poison the AllMetadata cache: i.e. a single-package read must not seed
   -- the cache with a singleton map that readAllMetadata would mistake for the
   -- complete set.
@@ -103,15 +103,15 @@ spec = do
     , { name: "control", version: "6.0.0", compilers: [ "0.15.15" ] }
     ]
 
-  -- | Run the REGISTRY effect - can't use the mock here because the regression
+  -- | Run the REGISTRY_READ effect - can't use the mock here because the regression
   -- | we are testing is in the caching code of the handle
   runRealRegistry
     :: forall a
      . RegistryEnv
-    -> Run (REGISTRY + GITHUB + LOG + EXCEPT String + AFF + EFFECT + ()) a
+    -> Run (REGISTRY_READ + GITHUB + LOG + EXCEPT String + AFF + EFFECT + ()) a
     -> Aff a
   runRealRegistry env =
-    Registry.interpret (Registry.handle env)
+    Registry.interpretRead (Registry.handleRead env)
       >>> GitHub.interpret handleGitHubStub
       >>> Log.interpret (\(Log _ _ next) -> pure next)
       >>> Except.catch (\err -> Run.liftAff (Aff.throwError (Aff.error err)))
diff --git a/app/test/Test/Assert/Run.purs b/app/test/Test/Assert/Run.purs
index 82aa1385..a427bd84 100644
--- a/app/test/Test/Assert/Run.purs
+++ b/app/test/Test/Assert/Run.purs
@@ -43,7 +43,7 @@ import Registry.App.Effect.PackageSets (PACKAGE_SETS, PackageSets(..))
 import Registry.App.Effect.PackageSets as PackageSets
 import Registry.App.Effect.Pursuit (PURSUIT, Pursuit(..))
 import Registry.App.Effect.Pursuit as Pursuit
-import Registry.App.Effect.Registry (REGISTRY, Registry(..))
+import Registry.App.Effect.Registry (REGISTRY, RegistryRead(..), RegistryWrite(..))
 import Registry.App.Effect.Registry as Registry
 import Registry.App.Effect.Source (FetchError(..), SOURCE, Source(..))
 import Registry.App.Effect.Source as Source
@@ -134,8 +134,15 @@ runTestEffects env operation = Aff.attempt do
   githubCache <- liftEffect Cache.newCacheRef
   operation
     # Pursuit.interpret (handlePursuitMock { metadataRef: env.metadata, excludes: env.pursuitExcludes })
-    # Registry.interpret
-        ( handleRegistryMock
+    # Registry.interpretWrite
+        ( handleRegistryWriteMock
+            { metadataRef: env.metadata
+            , indexRef: env.index
+            , failurePlan: env.failurePlan
+            }
+        )
+    # Registry.interpretRead
+        ( handleRegistryReadMock
             { metadataRef: env.metadata
             , indexRef: env.index
             , failurePlan: env.failurePlan
@@ -173,7 +180,8 @@ runRegistryMock :: forall a. Ref (Map PackageName Metadata) -> Ref ManifestIndex
 runRegistryMock metadataRef indexRef operation = do
   failurePlan <- liftEffect $ Ref.new []
   operation
-    # Registry.interpret (handleRegistryMock { metadataRef, indexRef, failurePlan })
+    # Registry.interpretWrite (handleRegistryWriteMock { metadataRef, indexRef, failurePlan })
+    # Registry.interpretRead (handleRegistryReadMock { metadataRef, indexRef, failurePlan })
     # runBaseEffects
 
 runGitHubCacheMemory :: forall r a. CacheRef -> Run (GITHUB_CACHE + LOG + EFFECT + r) a -> Run (LOG + EFFECT + r) a
@@ -210,12 +218,34 @@ type RegistryMockEnv =
   , failurePlan :: Ref (Array TestFailure)
   }
 
-handleRegistryMock :: forall r a. RegistryMockEnv -> Registry a -> Run (AFF + EFFECT + r) a
-handleRegistryMock env = case _ of
+handleRegistryReadMock :: forall r a. RegistryMockEnv -> RegistryRead a -> Run (AFF + EFFECT + r) a
+handleRegistryReadMock env = case _ of
   ReadManifest name version reply -> do
     index <- Run.liftEffect (Ref.read env.indexRef)
     pure $ reply $ Right $ ManifestIndex.lookup name version index
 
+  ReadAllManifests reply -> do
+    index <- Run.liftEffect (Ref.read env.indexRef)
+    pure $ reply $ Right index
+
+  ReadMetadata name reply -> do
+    metadata <- Run.liftEffect (Ref.read env.metadataRef)
+    pure $ reply $ Right $ Map.lookup name metadata
+
+  ReadAllMetadata reply -> do
+    metadata <- Run.liftEffect (Ref.read env.metadataRef)
+    pure $ reply $ Right metadata
+
+  -- FIXME: Actually reply with a package set
+  ReadLatestPackageSet reply ->
+    pure $ reply $ Right Nothing
+
+  -- FIXME: Actually reply with a package set
+  ReadAllPackageSets reply ->
+    pure $ reply $ Right Map.empty
+
+handleRegistryWriteMock :: forall r a. RegistryMockEnv -> RegistryWrite a -> Run (AFF + EFFECT + r) a
+handleRegistryWriteMock env = case _ of
   WriteManifest manifest reply -> do
     failWrite <- consumeFailure FailManifestWrite env.failurePlan
     if failWrite then do
@@ -236,14 +266,6 @@ handleRegistryMock env = case _ of
         Run.liftEffect (Ref.write index' env.indexRef)
         pure $ reply $ Right unit
 
-  ReadAllManifests reply -> do
-    index <- Run.liftEffect (Ref.read env.indexRef)
-    pure $ reply $ Right index
-
-  ReadMetadata name reply -> do
-    metadata <- Run.liftEffect (Ref.read env.metadataRef)
-    pure $ reply $ Right $ Map.lookup name metadata
-
   WriteMetadata name metadata reply -> do
     failWrite <- consumeFailure FailMetadataWrite env.failurePlan
     if failWrite then do
@@ -252,22 +274,10 @@ handleRegistryMock env = case _ of
       Run.liftEffect (Ref.modify_ (Map.insert name metadata) env.metadataRef)
       pure $ reply $ Right unit
 
-  ReadAllMetadata reply -> do
-    metadata <- Run.liftEffect (Ref.read env.metadataRef)
-    pure $ reply $ Right metadata
-
-  -- FIXME: Actually reply with a package set
-  ReadLatestPackageSet reply ->
-    pure $ reply $ Right Nothing
-
   -- FIXME: Actually write package set
   WritePackageSet _packageSet _message reply ->
     pure $ reply $ Right unit
 
-  -- FIXME: Actually reply with a package set
-  ReadAllPackageSets reply ->
-    pure $ reply $ Right Map.empty
-
   -- FIXME: Actually mirror the package set
   MirrorPackageSet _packageSet reply ->
     pure $ reply $ Right unit
diff --git a/scripts/src/DailyImporter.purs b/scripts/src/DailyImporter.purs
index 52c75a1e..cf53e37e 100644
--- a/scripts/src/DailyImporter.purs
+++ b/scripts/src/DailyImporter.purs
@@ -40,7 +40,7 @@ import Registry.App.Effect.GitHub (GITHUB)
 import Registry.App.Effect.GitHub as GitHub
 import Registry.App.Effect.Log (LOG)
 import Registry.App.Effect.Log as Log
-import Registry.App.Effect.Registry (REGISTRY)
+import Registry.App.Effect.Registry (REGISTRY_READ)
 import Registry.App.Effect.Registry as Registry
 import Registry.App.Legacy.LenientVersion as LenientVersion
 import Registry.Foreign.Octokit as Octokit
@@ -100,7 +100,7 @@ main = launchAff_ do
 
   runDailyImport mode resourceEnv.registryApiUrl
     # Except.runExcept
-    # Registry.interpret (Registry.handle registryEnv)
+    # Registry.interpretRead (Registry.handleRead registryEnv)
     # GitHub.interpret (GitHub.handle { octokit, cache, ref: githubCacheRef })
     # Log.interpret (Log.handleTerminal Verbose)
     # Env.runResourceEnv resourceEnv
@@ -111,7 +111,7 @@ main = launchAff_ do
         liftEffect $ Process.exit' 1
       Right _ -> pure unit
 
-type DailyImportEffects = (REGISTRY + GITHUB + LOG + RESOURCE_ENV + EXCEPT String + AFF + EFFECT + ())
+type DailyImportEffects = (REGISTRY_READ + GITHUB + LOG + RESOURCE_ENV + EXCEPT String + AFF + EFFECT + ())
 
 runDailyImport :: Mode -> URL -> Run DailyImportEffects Unit
 runDailyImport mode registryApiUrl = do
diff --git a/scripts/src/PackageSetUpdater.purs b/scripts/src/PackageSetUpdater.purs
index 35acc5cb..41026a7c 100644
--- a/scripts/src/PackageSetUpdater.purs
+++ b/scripts/src/PackageSetUpdater.purs
@@ -37,7 +37,7 @@ import Registry.App.Effect.GitHub as GitHub
 import Registry.App.Effect.Log (LOG)
 import Registry.App.Effect.Log as Log
 import Registry.App.Effect.PackageSets as PackageSets
-import Registry.App.Effect.Registry (REGISTRY)
+import Registry.App.Effect.Registry (REGISTRY_READ)
 import Registry.App.Effect.Registry as Registry
 import Registry.Foreign.Octokit as Octokit
 import Registry.Operation (PackageSetOperation(..))
@@ -98,7 +98,7 @@ main = launchAff_ do
 
   runPackageSetUpdater mode resourceEnv.registryApiUrl
     # Except.runExcept
-    # Registry.interpret (Registry.handle registryEnv)
+    # Registry.interpretRead (Registry.handleRead registryEnv)
     # GitHub.interpret (GitHub.handle { octokit, cache, ref: githubCacheRef })
     # Log.interpret (Log.handleTerminal Normal)
     # Env.runResourceEnv resourceEnv
@@ -109,7 +109,7 @@ main = launchAff_ do
         liftEffect $ Process.exit' 1
       Right _ -> pure unit
 
-type PackageSetUpdaterEffects = (REGISTRY + GITHUB + LOG + RESOURCE_ENV + EXCEPT String + AFF + EFFECT + ())
+type PackageSetUpdaterEffects = (REGISTRY_READ + GITHUB + LOG + RESOURCE_ENV + EXCEPT String + AFF + EFFECT + ())
 
 runPackageSetUpdater :: Mode -> URL -> Run PackageSetUpdaterEffects Unit
 runPackageSetUpdater mode registryApiUrl = do
diff --git a/scripts/src/PackageTransferrer.purs b/scripts/src/PackageTransferrer.purs
index dbfbf225..9e0e463c 100644
--- a/scripts/src/PackageTransferrer.purs
+++ b/scripts/src/PackageTransferrer.purs
@@ -37,7 +37,7 @@ import Registry.App.Effect.GitHub (GITHUB)
 import Registry.App.Effect.GitHub as GitHub
 import Registry.App.Effect.Log (LOG)
 import Registry.App.Effect.Log as Log
-import Registry.App.Effect.Registry (REGISTRY)
+import Registry.App.Effect.Registry (REGISTRY_READ)
 import Registry.App.Effect.Registry as Registry
 import Registry.Foreign.Octokit as Octokit
 import Registry.Location (Location(..))
@@ -103,7 +103,7 @@ main = launchAff_ do
 
   runPackageTransferrer mode maybePrivateKey resourceEnv.registryApiUrl
     # Except.runExcept
-    # Registry.interpret (Registry.handle registryEnv)
+    # Registry.interpretRead (Registry.handleRead registryEnv)
     # GitHub.interpret (GitHub.handle { octokit, cache, ref: githubCacheRef })
     # Log.interpret (Log.handleTerminal Normal)
     # Env.runResourceEnv resourceEnv
@@ -114,7 +114,7 @@ main = launchAff_ do
         liftEffect $ Process.exit' 1
       Right _ -> pure unit
 
-type PackageTransferrerEffects = (REGISTRY + GITHUB + LOG + RESOURCE_ENV + EXCEPT String + AFF + EFFECT + ())
+type PackageTransferrerEffects = (REGISTRY_READ + GITHUB + LOG + RESOURCE_ENV + EXCEPT String + AFF + EFFECT + ())
 
 runPackageTransferrer :: Mode -> Maybe String -> URL -> Run PackageTransferrerEffects Unit
 runPackageTransferrer mode maybePrivateKey registryApiUrl = do
diff --git a/scripts/src/VerifyIntegrity.purs b/scripts/src/VerifyIntegrity.purs
index 414cb813..96c7fa5f 100644
--- a/scripts/src/VerifyIntegrity.purs
+++ b/scripts/src/VerifyIntegrity.purs
@@ -91,7 +91,7 @@ main = launchAff_ do
     let
       interpret =
         Except.catch (\error -> Run.liftEffect (Console.log error *> Process.exit' 1))
-          >>> Registry.interpret (Registry.handle registryEnv)
+          >>> Registry.interpretRead (Registry.handleRead registryEnv)
           >>> GitHub.interpret (GitHub.handle { octokit, cache, ref: githubCacheRef })
           >>> Env.runResourceEnv resourceEnv
           >>> Log.interpret (\log -> Log.handleTerminal Normal log *> Log.handleFs Verbose logPath log)
@@ -127,7 +127,7 @@ main = launchAff_ do
     let
       interpret =
         Except.catch (\error -> Run.liftEffect (Console.log error *> Process.exit' 1))
-          >>> Registry.interpret (Registry.handle registryEnv)
+          >>> Registry.interpretRead (Registry.handleRead registryEnv)
           >>> Storage.interpret (Storage.handleS3 { s3, cache })
           >>> GitHub.interpret (GitHub.handle { octokit, cache, ref: githubCacheRef })
           >>> Env.runResourceEnv resourceEnv

From 83fb1c30a1638ec4c13621f578851bfdc681aaa6 Mon Sep 17 00:00:00 2001
From: Thomas Honeyman <hello@thomashoneyman.com>
Date: Wed, 22 Jul 2026 20:27:58 +0000
Subject: [PATCH 2/8] Narrow registry read interpreter dependencies

Amp-Thread-ID: https://ampcode.com/threads/T-019f8b54-076c-701a-863f-75106cd6f5bd

Co-authored-by: Thomas Honeyman <admin@thomashoneyman.com>
---
 app-e2e/src/Test/E2E/Scripts.purs  |  38 +--
 app/src/App/Effect/Registry.purs   | 395 ++++++++++++++---------------
 app/test/App/Effect/Registry.purs  |  10 +-
 scripts/src/PackageSetUpdater.purs |  14 +-
 scripts/src/VerifyIntegrity.purs   |  13 +-
 5 files changed, 221 insertions(+), 249 deletions(-)

diff --git a/app-e2e/src/Test/E2E/Scripts.purs b/app-e2e/src/Test/E2E/Scripts.purs
index 72a05661..424eec9a 100644
--- a/app-e2e/src/Test/E2E/Scripts.purs
+++ b/app-e2e/src/Test/E2E/Scripts.purs
@@ -149,8 +149,13 @@ spec = do
         Just _ -> Assert.fail "Expected PackageSetJob but got different job type"
         Nothing -> Assert.fail "Expected package set job to be enqueued"
 
--- | Common environment for running registry scripts in E2E tests
-type ScriptSetup =
+-- | Common environment for running read-only registry scripts in E2E tests
+type RegistryScriptSetup =
+  { resourceEnv :: Env.ResourceEnv
+  , registryEnv :: Registry.RegistryEnv
+  }
+
+type GitHubScriptSetup =
   { privateKey :: String
   , resourceEnv :: Env.ResourceEnv
   , registryEnv :: Registry.RegistryEnv
@@ -159,17 +164,12 @@ type ScriptSetup =
   , githubCacheRef :: Cache.CacheRef
   }
 
--- | Set up common environment for running registry scripts
-setupScript :: E2E ScriptSetup
-setupScript = do
-  { stateDir, privateKey } <- ask
+setupRegistryScript :: E2E RegistryScriptSetup
+setupRegistryScript = do
+  { stateDir } <- ask
   liftEffect $ Process.chdir stateDir
   resourceEnv <- liftEffect Env.lookupResourceEnv
-  token <- liftEffect $ Env.lookupRequired Env.githubToken
-  githubCacheRef <- liftAff Cache.newCacheRef
   registryCacheRef <- liftAff Cache.newCacheRef
-  let cache = Path.concat [ stateDir, "scratch", ".cache" ]
-  octokit <- liftAff $ Octokit.newOctokit token resourceEnv.githubApiUrl
   debouncer <- liftAff Registry.newDebouncer
   let
     registryEnv :: Registry.RegistryEnv
@@ -182,12 +182,22 @@ setupScript = do
       , debouncer
       , cacheRef: registryCacheRef
       }
+  pure { resourceEnv, registryEnv }
+
+setupGitHubScript :: E2E GitHubScriptSetup
+setupGitHubScript = do
+  { stateDir, privateKey } <- ask
+  { resourceEnv, registryEnv } <- setupRegistryScript
+  token <- liftEffect $ Env.lookupRequired Env.githubToken
+  githubCacheRef <- liftAff Cache.newCacheRef
+  let cache = Path.concat [ stateDir, "scratch", ".cache" ]
+  octokit <- liftAff $ Octokit.newOctokit token resourceEnv.githubApiUrl
   pure { privateKey, resourceEnv, registryEnv, octokit, cache, githubCacheRef }
 
 -- | Run the DailyImporter script in Submit mode
 runDailyImporterScript :: E2E Unit
 runDailyImporterScript = do
-  { resourceEnv, registryEnv, octokit, cache, githubCacheRef } <- setupScript
+  { resourceEnv, registryEnv, octokit, cache, githubCacheRef } <- setupGitHubScript
   result <- liftAff
     $ DailyImporter.runDailyImport DailyImporter.Submit resourceEnv.registryApiUrl
     # Except.runExcept
@@ -203,7 +213,7 @@ runDailyImporterScript = do
 -- | Run the PackageTransferrer script in Submit mode
 runPackageTransferrerScript :: E2E Unit
 runPackageTransferrerScript = do
-  { privateKey, resourceEnv, registryEnv, octokit, cache, githubCacheRef } <- setupScript
+  { privateKey, resourceEnv, registryEnv, octokit, cache, githubCacheRef } <- setupGitHubScript
   result <- liftAff
     $ PackageTransferrer.runPackageTransferrer PackageTransferrer.Submit (Just privateKey) resourceEnv.registryApiUrl
     # Except.runExcept
@@ -219,14 +229,12 @@ runPackageTransferrerScript = do
 -- | Run the PackageSetUpdater script in Submit mode
 runPackageSetUpdaterScript :: E2E Unit
 runPackageSetUpdaterScript = do
-  { resourceEnv, registryEnv, octokit, cache, githubCacheRef } <- setupScript
+  { resourceEnv, registryEnv } <- setupRegistryScript
   result <- liftAff
     $ PackageSetUpdater.runPackageSetUpdater PackageSetUpdater.Submit resourceEnv.registryApiUrl
     # Except.runExcept
     # Registry.interpretRead (Registry.handleRead registryEnv)
-    # GitHub.interpret (GitHub.handle { octokit, cache, ref: githubCacheRef })
     # Log.interpret (Log.handleTerminal Quiet)
-    # Env.runResourceEnv resourceEnv
     # Run.runBaseAff'
   case result of
     Left err -> liftAff $ Aff.throwError $ Aff.error $ "PackageSetUpdater failed: " <> err
diff --git a/app/src/App/Effect/Registry.purs b/app/src/App/Effect/Registry.purs
index 7ea05e47..4314990f 100644
--- a/app/src/App/Effect/Registry.purs
+++ b/app/src/App/Effect/Registry.purs
@@ -230,28 +230,86 @@ defaultRepos =
   , legacyPackageSets: Legacy.PackageSet.legacyPackageSetsRepo
   }
 
-data RegistryOperation a
-  = ReadOperation (RegistryRead a)
-  | WriteOperation (RegistryWrite a)
+-- | Get the upstream address associated with a repository key.
+repoAddress :: RegistryEnv -> RepoKey -> Address
+repoAddress env = case _ of
+  RegistryRepo -> env.repos.registry
+  ManifestIndexRepo -> env.repos.manifestIndex
+  LegacyPackageSetsRepo -> env.repos.legacyPackageSets
+
+-- | Get the local path for the checkout associated with a repository key.
+repoPath :: RegistryEnv -> RepoKey -> FilePath
+repoPath env = case _ of
+  RegistryRepo -> Path.concat [ env.workdir, "registry" ]
+  ManifestIndexRepo -> Path.concat [ env.workdir, "registry-index" ]
+  LegacyPackageSetsRepo -> Path.concat [ env.workdir, "package-sets" ]
+
+-- | Get the repository at the given key, recording whether the pull or clone
+-- | had any effect (ie. if the repo was already up-to-date).
+pull :: forall r. RegistryEnv -> RepoKey -> Run (LOG + AFF + EFFECT + r) (Either String GitResult)
+pull env repoKey = do
+  let
+    path = repoPath env repoKey
+    address = repoAddress env repoKey
+    fetchLatest = do
+      Log.debug $ "Fetching repo at path " <> path
+      -- First, we need to verify whether we should clone or pull.
+      Run.liftAff (Aff.attempt (FS.Aff.stat path)) >>= case _ of
+        -- When the repository doesn't exist at the given file path we can go
+        -- straight to a clone.
+        Left _ -> do
+          let formatted = address.owner <> "/" <> address.repo
+          let url = "https://github.com/" <> formatted <> ".git"
+          Log.debug $ "Didn't find " <> formatted <> " locally, cloning..."
+          Run.liftAff (Git.gitCLI [ "clone", url, path ] Nothing) >>= case _ of
+            Left err -> do
+              Log.error $ "Failed to git clone repo " <> url <> " due to a git error: " <> err
+              pure $ Left $ "Could not read the repository at " <> formatted
+            Right _ ->
+              pure $ Right Git.Changed
+
+        -- If it does, then we should pull.
+        Right _ -> do
+          Log.debug $ "Found repo at path " <> path <> ", pulling latest."
+          result <- Git.gitPull { address, pullMode: env.pull } path
+          pure result
+
+  -- Check if the repo directory exists before consulting the debouncer.
+  -- This ensures that if the scratch directory is deleted (e.g., for test
+  -- isolation), we always re-clone rather than returning a stale NoChange.
+  repoExists <- Run.liftAff $ Aff.attempt (FS.Aff.stat path)
+  case repoExists of
+    Left _ -> do
+      -- Repo doesn't exist, bypass debouncer entirely and clone fresh
+      result <- fetchLatest
+      now <- nowUTC
+      Run.liftEffect $ Ref.modify_ (Map.insert path now) env.debouncer
+      pure result
+    Right _ -> do
+      -- Repo exists, check debouncer
+      now <- nowUTC
+      debouncers <- Run.liftEffect $ Ref.read env.debouncer
+      case Map.lookup path debouncers of
+        -- We will be behind the upstream by at most this amount of time.
+        Just prev | DateTime.diff now prev <= Duration.Minutes 1.0 ->
+          pure $ Right Git.NoChange
+        -- If we didn't debounce, then we should fetch the upstream.
+        _ -> do
+          result <- fetchLatest
+          Run.liftEffect $ Ref.modify_ (Map.insert path now) env.debouncer
+          pure result
 
 -- | Handle the REGISTRY_READ effect by downloading the registry and
 -- | registry-index repositories locally and reading their contents from disk.
-handleRead :: forall r a. RegistryEnv -> RegistryRead a -> Run (GITHUB + LOG + AFF + EFFECT + r) a
-handleRead env = handleOperation env <<< ReadOperation
-
--- | Handle the REGISTRY_WRITE effect by writing registry resources to disk.
--- | Writes can optionally commit and push to the upstream Git repository.
-handleWrite :: forall r a. RegistryEnv -> RegistryWrite a -> Run (GITHUB + LOG + AFF + EFFECT + r) a
-handleWrite env = handleOperation env <<< WriteOperation
-
--- | These handlers share a memory-only cache: we do not want to cache on the
--- | file system or other storage because they rely on the registry Git
--- | repositories instead.
-handleOperation :: forall r a. RegistryEnv -> RegistryOperation a -> Run (GITHUB + LOG + AFF + EFFECT + r) a
-handleOperation env = Cache.interpret _registryCache (Cache.handleMemory env.cacheRef) <<< case _ of
-  ReadOperation (ReadManifest name version reply) -> do
+-- |
+-- | This handler uses the same memory-only cache as the write handler: we do
+-- | not want to cache on the file system or other storage because the handlers
+-- | rely on the registry Git repositories instead.
+handleRead :: forall r a. RegistryEnv -> RegistryRead a -> Run (LOG + AFF + EFFECT + r) a
+handleRead env = Cache.interpret _registryCache (Cache.handleMemory env.cacheRef) <<< case _ of
+  ReadManifest name version reply -> do
     let formatted = formatPackageVersion name version
-    handleOperation env (ReadOperation (ReadAllManifests identity)) >>= case _ of
+    handleRead env (ReadAllManifests identity) >>= case _ of
       Left error -> pure $ reply $ Left error
       Right index -> case ManifestIndex.lookup name version index of
         Nothing -> do
@@ -260,63 +318,15 @@ handleOperation env = Cache.interpret _registryCache (Cache.handleMemory env.cac
         Just manifest -> do
           pure $ reply $ Right $ Just manifest
 
-  WriteOperation (WriteManifest manifest@(Manifest { name, version }) reply) -> map (map reply) Except.runExcept do
-    let formatted = formatPackageVersion name version
-    Log.info $ "Writing manifest for " <> formatted <> ":\n" <> printJson Manifest.codec manifest
-    index <- Except.rethrow =<< handleOperation env (ReadOperation (ReadAllManifests identity))
-    case ManifestIndex.insert ManifestIndex.ConsiderRanges manifest index of
-      Left error ->
-        Except.throw $ Array.fold
-          [ "Can't insert " <> formatted <> " into manifest index because it has unsatisfied dependencies:"
-          , printJson (Internal.Codec.packageMap Range.codec) error
-          ]
-      Right updated -> do
-        result <- writeCommitPush (CommitManifestEntry name) \indexPath -> do
-          ManifestIndex.insertIntoEntryFile indexPath manifest >>= case _ of
-            Left error -> Except.throw $ "Could not insert manifest for " <> formatted <> " into its entry file in WriteManifest: " <> error
-            Right _ -> pure $ Just $ "Update manifest for " <> formatted
-        case result of
-          Left error -> Except.throw $ "Failed to write and commit manifest: " <> error
-          Right r -> do
-            case r of
-              Git.NoChange -> Log.info "Did not commit manifest because it did not change."
-              Git.Changed -> Log.info "Wrote and committed manifest."
-            Cache.put _registryCache AllManifests updated
-
-  WriteOperation (DeleteManifest name version reply) -> map (map reply) Except.runExcept do
-    let formatted = formatPackageVersion name version
-    Log.info $ "Deleting manifest for " <> formatted
-    index <- Except.rethrow =<< handleOperation env (ReadOperation (ReadAllManifests identity))
-    case ManifestIndex.delete ManifestIndex.ConsiderRanges name version index of
-      Left error ->
-        Except.throw $ Array.fold
-          [ "Can't delete " <> formatted <> " from manifest index because it would produce unsatisfied dependencies:"
-          , printJson (Internal.Codec.packageMap (Internal.Codec.versionMap (Internal.Codec.packageMap Range.codec))) error
-          ]
-      Right updated -> do
-        commitResult <- writeCommitPush (CommitManifestEntry name) \indexPath -> do
-          ManifestIndex.removeFromEntryFile indexPath name version >>= case _ of
-            Left error -> Except.throw $ "Could not remove manifest for " <> formatted <> " from its entry file in DeleteManifest: " <> error
-            Right _ -> pure $ Just $ "Remove manifest entry for " <> formatted
-        case commitResult of
-          Left error -> Except.throw $ "Failed to delete and commit manifest: " <> error
-          Right r -> do
-            case r of
-              Git.NoChange ->
-                Log.info "Did not commit manifest because it already didn't exist."
-              Git.Changed ->
-                Log.info "Wrote and committed manifest."
-            Cache.put _registryCache AllManifests updated
-
-  ReadOperation (ReadAllManifests reply) -> map (map reply) Except.runExcept do
+  ReadAllManifests reply -> map (map reply) Except.runExcept do
     let
       refreshIndex = do
-        let indexPath = repoPath ManifestIndexRepo
+        let indexPath = repoPath env ManifestIndexRepo
         index <- readManifestIndexFromDisk indexPath
         Cache.put _registryCache AllManifests index
         pure index
 
-    pull ManifestIndexRepo >>= case _ of
+    pull env ManifestIndexRepo >>= case _ of
       Left error ->
         Except.throw $ "Could not read manifests because the manifest index repo could not be checked: " <> error
       Right Git.NoChange -> do
@@ -330,9 +340,9 @@ handleOperation env = Cache.interpret _registryCache (Cache.handleMemory env.cac
         Log.info "Manifest index has changed, replacing cache..."
         refreshIndex
 
-  ReadOperation (ReadMetadata name reply) -> map (map reply) Except.runExcept do
+  ReadMetadata name reply -> map (map reply) Except.runExcept do
     let printedName = PackageName.print name
-    let dir = repoPath RegistryRepo
+    let dir = repoPath env RegistryRepo
 
     let
       path = Path.concat [ dir, Constants.metadataDirectory, printedName <> ".json" ]
@@ -362,7 +372,7 @@ handleOperation env = Cache.interpret _registryCache (Cache.handleMemory env.cac
                 Log.debug $ "Successfully read metadata for " <> printedName <> " from path " <> path
                 pure (Just metadata)
 
-    pull RegistryRepo >>= case _ of
+    pull env RegistryRepo >>= case _ of
       Left error ->
         Except.throw $ "Could not read metadata because the registry repo could not be checked: " <> error
 
@@ -390,38 +400,17 @@ handleOperation env = Cache.interpret _registryCache (Cache.handleMemory env.cac
         Cache.delete _registryCache AllMetadata
         readMetadataFromDisk
 
-  WriteOperation (WriteMetadata name metadata reply) -> map (map reply) Except.runExcept do
-    let printedName = PackageName.print name
-    Log.info $ "Writing metadata for " <> printedName
-    Log.debug $ printJson Metadata.codec metadata
-    commitResult <- writeCommitPush (CommitMetadataEntry name) \dir -> do
-      let path = Path.concat [ dir, Constants.metadataDirectory, printedName <> ".json" ]
-      Run.liftAff (Aff.attempt (writeJsonFile Metadata.codec path metadata)) >>= case _ of
-        Left fsError -> Except.throw $ "Failed to write metadata for " <> printedName <> " to path " <> path <> " do to an fs error: " <> Aff.message fsError
-        Right _ -> pure $ Just $ "Update metadata for " <> printedName
-    case commitResult of
-      Left error -> Except.throw $ "Failed to write and commit metadata: " <> error
-      Right r -> do
-        case r of
-          Git.NoChange ->
-            Log.info "Did not commit metadata because it was unchanged."
-          Git.Changed ->
-            Log.info "Wrote and committed metadata."
-        cache <- Cache.get _registryCache AllMetadata
-        for_ cache \cached ->
-          Cache.put _registryCache AllMetadata (Map.insert name metadata cached)
-
-  ReadOperation (ReadAllMetadata reply) -> map (map reply) Except.runExcept do
+  ReadAllMetadata reply -> map (map reply) Except.runExcept do
     let
       refreshMetadata = do
-        let dir = repoPath RegistryRepo
+        let dir = repoPath env RegistryRepo
         let metadataDir = Path.concat [ dir, Constants.metadataDirectory ]
         Log.info $ "Reading metadata for all packages from directory " <> metadataDir
         allMetadata <- readAllMetadataFromDisk metadataDir
         Cache.put _registryCache AllMetadata allMetadata
         pure allMetadata
 
-    pull RegistryRepo >>= case _ of
+    pull env RegistryRepo >>= case _ of
       Left error ->
         Except.throw $ "Could not read metadata because the registry repo could not be checked: " <> error
       Right Git.NoChange -> do
@@ -435,11 +424,11 @@ handleOperation env = Cache.interpret _registryCache (Cache.handleMemory env.cac
         Log.info "Registry repo has changed, replacing metadata cache..."
         refreshMetadata
 
-  ReadOperation (ReadLatestPackageSet reply) -> map (map reply) Except.runExcept do
-    pull RegistryRepo >>= case _ of
+  ReadLatestPackageSet reply -> map (map reply) Except.runExcept do
+    pull env RegistryRepo >>= case _ of
       Left error -> Except.throw $ "Could not read package sets because the registry repo could not be checked: " <> error
       Right _ -> pure unit
-    let dir = repoPath RegistryRepo
+    let dir = repoPath env RegistryRepo
     let packageSetsDir = Path.concat [ dir, Constants.packageSetsDirectory ]
     Log.info $ "Reading latest package set from directory " <> packageSetsDir
     versions <- listPackageSetVersions packageSetsDir
@@ -456,27 +445,11 @@ handleOperation env = Cache.interpret _registryCache (Cache.handleMemory env.cac
             Log.debug $ "Successfully read package set " <> printed
             pure $ Just set
 
-  WriteOperation (WritePackageSet set@(PackageSet { version }) message reply) -> map (map reply) Except.runExcept do
-    pull RegistryRepo >>= case _ of
+  ReadAllPackageSets reply -> map (map reply) Except.runExcept do
+    pull env RegistryRepo >>= case _ of
       Left error -> Except.throw $ "Could not read package sets because the registry repo could not be checked: " <> error
       Right _ -> pure unit
-    let name = Version.print version
-    Log.info $ "Writing package set " <> name
-    commitResult <- writeCommitPush (CommitPackageSet version) \dir -> do
-      let path = Path.concat [ dir, Constants.packageSetsDirectory, name <> ".json" ]
-      Run.liftAff (Aff.attempt (writeJsonFile PackageSet.codec path set)) >>= case _ of
-        Left fsError -> Except.throw $ "Failed to write package set " <> name <> " to path " <> path <> " do to an fs error: " <> Aff.message fsError
-        Right _ -> pure $ Just message
-    case commitResult of
-      Left error -> Except.throw $ "Failed to write and commit package set: " <> error
-      Right Git.NoChange -> Log.info "Did not commit package set because it was unchanged."
-      Right Git.Changed -> Log.info "Wrote and committed package set."
-
-  ReadOperation (ReadAllPackageSets reply) -> map (map reply) Except.runExcept do
-    pull RegistryRepo >>= case _ of
-      Left error -> Except.throw $ "Could not read package sets because the registry repo could not be checked: " <> error
-      Right _ -> pure unit
-    let dir = repoPath RegistryRepo
+    let dir = repoPath env RegistryRepo
     let packageSetsDir = Path.concat [ dir, Constants.packageSetsDirectory ]
     Log.info $ "Reading all package sets from directory " <> packageSetsDir
     versions <- listPackageSetVersions packageSetsDir
@@ -494,13 +467,104 @@ handleOperation env = Cache.interpret _registryCache (Cache.handleMemory env.cac
         Log.warn $ "Some package sets could not be read and were skipped: " <> Array.foldMap format xs
         pure $ Map.fromFoldable results.success
 
+-- | Handle the REGISTRY_WRITE effect by writing registry resources to disk.
+-- | Writes can optionally commit and push to the upstream Git repository.
+-- |
+-- | This handler uses the same memory-only cache as the read handler.
+handleWrite :: forall r a. RegistryEnv -> RegistryWrite a -> Run (GITHUB + LOG + AFF + EFFECT + r) a
+handleWrite env = Cache.interpret _registryCache (Cache.handleMemory env.cacheRef) <<< case _ of
+  WriteManifest manifest@(Manifest { name, version }) reply -> map (map reply) Except.runExcept do
+    let formatted = formatPackageVersion name version
+    Log.info $ "Writing manifest for " <> formatted <> ":\n" <> printJson Manifest.codec manifest
+    index <- Except.rethrow =<< handleRead env (ReadAllManifests identity)
+    case ManifestIndex.insert ManifestIndex.ConsiderRanges manifest index of
+      Left error ->
+        Except.throw $ Array.fold
+          [ "Can't insert " <> formatted <> " into manifest index because it has unsatisfied dependencies:"
+          , printJson (Internal.Codec.packageMap Range.codec) error
+          ]
+      Right updated -> do
+        result <- writeCommitPush (CommitManifestEntry name) \indexPath -> do
+          ManifestIndex.insertIntoEntryFile indexPath manifest >>= case _ of
+            Left error -> Except.throw $ "Could not insert manifest for " <> formatted <> " into its entry file in WriteManifest: " <> error
+            Right _ -> pure $ Just $ "Update manifest for " <> formatted
+        case result of
+          Left error -> Except.throw $ "Failed to write and commit manifest: " <> error
+          Right r -> do
+            case r of
+              Git.NoChange -> Log.info "Did not commit manifest because it did not change."
+              Git.Changed -> Log.info "Wrote and committed manifest."
+            Cache.put _registryCache AllManifests updated
+
+  DeleteManifest name version reply -> map (map reply) Except.runExcept do
+    let formatted = formatPackageVersion name version
+    Log.info $ "Deleting manifest for " <> formatted
+    index <- Except.rethrow =<< handleRead env (ReadAllManifests identity)
+    case ManifestIndex.delete ManifestIndex.ConsiderRanges name version index of
+      Left error ->
+        Except.throw $ Array.fold
+          [ "Can't delete " <> formatted <> " from manifest index because it would produce unsatisfied dependencies:"
+          , printJson (Internal.Codec.packageMap (Internal.Codec.versionMap (Internal.Codec.packageMap Range.codec))) error
+          ]
+      Right updated -> do
+        commitResult <- writeCommitPush (CommitManifestEntry name) \indexPath -> do
+          ManifestIndex.removeFromEntryFile indexPath name version >>= case _ of
+            Left error -> Except.throw $ "Could not remove manifest for " <> formatted <> " from its entry file in DeleteManifest: " <> error
+            Right _ -> pure $ Just $ "Remove manifest entry for " <> formatted
+        case commitResult of
+          Left error -> Except.throw $ "Failed to delete and commit manifest: " <> error
+          Right r -> do
+            case r of
+              Git.NoChange ->
+                Log.info "Did not commit manifest because it already didn't exist."
+              Git.Changed ->
+                Log.info "Wrote and committed manifest."
+            Cache.put _registryCache AllManifests updated
+
+  WriteMetadata name metadata reply -> map (map reply) Except.runExcept do
+    let printedName = PackageName.print name
+    Log.info $ "Writing metadata for " <> printedName
+    Log.debug $ printJson Metadata.codec metadata
+    commitResult <- writeCommitPush (CommitMetadataEntry name) \dir -> do
+      let path = Path.concat [ dir, Constants.metadataDirectory, printedName <> ".json" ]
+      Run.liftAff (Aff.attempt (writeJsonFile Metadata.codec path metadata)) >>= case _ of
+        Left fsError -> Except.throw $ "Failed to write metadata for " <> printedName <> " to path " <> path <> " do to an fs error: " <> Aff.message fsError
+        Right _ -> pure $ Just $ "Update metadata for " <> printedName
+    case commitResult of
+      Left error -> Except.throw $ "Failed to write and commit metadata: " <> error
+      Right r -> do
+        case r of
+          Git.NoChange ->
+            Log.info "Did not commit metadata because it was unchanged."
+          Git.Changed ->
+            Log.info "Wrote and committed metadata."
+        cache <- Cache.get _registryCache AllMetadata
+        for_ cache \cached ->
+          Cache.put _registryCache AllMetadata (Map.insert name metadata cached)
+
+  WritePackageSet set@(PackageSet { version }) message reply -> map (map reply) Except.runExcept do
+    pull env RegistryRepo >>= case _ of
+      Left error -> Except.throw $ "Could not read package sets because the registry repo could not be checked: " <> error
+      Right _ -> pure unit
+    let name = Version.print version
+    Log.info $ "Writing package set " <> name
+    commitResult <- writeCommitPush (CommitPackageSet version) \dir -> do
+      let path = Path.concat [ dir, Constants.packageSetsDirectory, name <> ".json" ]
+      Run.liftAff (Aff.attempt (writeJsonFile PackageSet.codec path set)) >>= case _ of
+        Left fsError -> Except.throw $ "Failed to write package set " <> name <> " to path " <> path <> " do to an fs error: " <> Aff.message fsError
+        Right _ -> pure $ Just message
+    case commitResult of
+      Left error -> Except.throw $ "Failed to write and commit package set: " <> error
+      Right Git.NoChange -> Log.info "Did not commit package set because it was unchanged."
+      Right Git.Changed -> Log.info "Wrote and committed package set."
+
   -- https://github.com/purescript/package-sets/blob/psc-0.15.4-20220829/release.sh
   -- https://github.com/purescript/package-sets/blob/psc-0.15.4-20220829/update-latest-compatible-sets.sh
-  WriteOperation (MirrorPackageSet set@(PackageSet { version }) reply) -> map (map reply) Except.runExcept do
+  MirrorPackageSet set@(PackageSet { version }) reply -> map (map reply) Except.runExcept do
     let name = Version.print version
     Log.info $ "Mirroring legacy package set " <> name <> " to the legacy package sets repo"
 
-    manifests <- Except.rethrow =<< handleOperation env (ReadOperation (ReadAllManifests identity))
+    manifests <- Except.rethrow =<< handleRead env (ReadAllManifests identity)
 
     Log.debug $ "Converting package set..."
     converted <- case Legacy.PackageSet.convertPackageSet manifests set of
@@ -508,7 +572,7 @@ handleOperation env = Cache.interpret _registryCache (Cache.handleMemory env.cac
       Right converted -> pure converted
 
     let printedTag = Legacy.PackageSet.printPscTag converted.tag
-    let legacyRepo = repoAddress LegacyPackageSetsRepo
+    let legacyRepo = repoAddress env LegacyPackageSetsRepo
 
     packageSetsTags <- GitHub.listTags legacyRepo >>= case _ of
       Left githubError ->
@@ -599,20 +663,6 @@ handleOperation env = Cache.interpret _registryCache (Cache.handleMemory env.cac
           Right Git.Changed ->
             Log.info "Pushed new tags to legacy registry."
   where
-  -- | Get the upstream address associated with a repository key
-  repoAddress :: RepoKey -> Address
-  repoAddress = case _ of
-    RegistryRepo -> env.repos.registry
-    ManifestIndexRepo -> env.repos.manifestIndex
-    LegacyPackageSetsRepo -> env.repos.legacyPackageSets
-
-  -- | Get local filepath for the checkout associated with a repository key
-  repoPath :: RepoKey -> FilePath
-  repoPath = case _ of
-    RegistryRepo -> Path.concat [ env.workdir, "registry" ]
-    ManifestIndexRepo -> Path.concat [ env.workdir, "registry-index" ]
-    LegacyPackageSetsRepo -> Path.concat [ env.workdir, "package-sets" ]
-
   -- | Write a file to the repository associated with the commit key, given a
   -- | callback that takes the file path of the repository on disk, writes the
   -- | file(s), and returns a commit message which is used to commit to the
@@ -620,10 +670,10 @@ handleOperation env = Cache.interpret _registryCache (Cache.handleMemory env.cac
   writeCommitPush :: CommitKey -> (FilePath -> Run _ (Maybe String)) -> Run _ (Either String GitResult)
   writeCommitPush commitKey write = do
     let repoKey = commitKeyToRepoKey commitKey
-    pull repoKey >>= case _ of
+    pull env repoKey >>= case _ of
       Left error -> pure (Left error)
       Right _ -> do
-        let path = repoPath repoKey
+        let path = repoPath env repoKey
         write path >>= case _ of
           Nothing -> pure $ Left $ "Failed to write file(s) to " <> path
           Just message -> commit commitKey message >>= case _ of
@@ -640,67 +690,12 @@ handleOperation env = Cache.interpret _registryCache (Cache.handleMemory env.cac
       Nothing -> pure (Right Git.NoChange)
       Just { head } -> pure (Left head)
 
-  -- | Get the repository at the given key, recording whether the pull or clone
-  -- | had any effect (ie. if the repo was already up-to-date).
-  pull :: RepoKey -> Run _ (Either String GitResult)
-  pull repoKey = do
-    let
-      path = repoPath repoKey
-      address = repoAddress repoKey
-      fetchLatest = do
-        Log.debug $ "Fetching repo at path " <> path
-        -- First, we need to verify whether we should clone or pull.
-        Run.liftAff (Aff.attempt (FS.Aff.stat path)) >>= case _ of
-          -- When the repository doesn't exist at the given file path we can go
-          -- straight to a clone.
-          Left _ -> do
-            let formatted = address.owner <> "/" <> address.repo
-            let url = "https://github.com/" <> formatted <> ".git"
-            Log.debug $ "Didn't find " <> formatted <> " locally, cloning..."
-            Run.liftAff (Git.gitCLI [ "clone", url, path ] Nothing) >>= case _ of
-              Left err -> do
-                Log.error $ "Failed to git clone repo " <> url <> " due to a git error: " <> err
-                pure $ Left $ "Could not read the repository at " <> formatted
-              Right _ ->
-                pure $ Right Git.Changed
-
-          -- If it does, then we should pull.
-          Right _ -> do
-            Log.debug $ "Found repo at path " <> path <> ", pulling latest."
-            result <- Git.gitPull { address, pullMode: env.pull } path
-            pure result
-
-    -- Check if the repo directory exists before consulting the debouncer.
-    -- This ensures that if the scratch directory is deleted (e.g., for test
-    -- isolation), we always re-clone rather than returning a stale NoChange.
-    repoExists <- Run.liftAff $ Aff.attempt (FS.Aff.stat path)
-    case repoExists of
-      Left _ -> do
-        -- Repo doesn't exist, bypass debouncer entirely and clone fresh
-        result <- fetchLatest
-        now <- nowUTC
-        Run.liftEffect $ Ref.modify_ (Map.insert path now) env.debouncer
-        pure result
-      Right _ -> do
-        -- Repo exists, check debouncer
-        now <- nowUTC
-        debouncers <- Run.liftEffect $ Ref.read env.debouncer
-        case Map.lookup path debouncers of
-          -- We will be behind the upstream by at most this amount of time.
-          Just prev | DateTime.diff now prev <= Duration.Minutes 1.0 ->
-            pure $ Right Git.NoChange
-          -- If we didn't debounce, then we should fetch the upstream.
-          _ -> do
-            result <- fetchLatest
-            Run.liftEffect $ Ref.modify_ (Map.insert path now) env.debouncer
-            pure result
-
   -- | Commit the file(s) indicated by the commit key with a commit message.
   commit :: CommitKey -> String -> Run _ (Either String GitResult)
   commit commitKey message' = do
     let
       repoKey = commitKeyToRepoKey commitKey
-      address = repoAddress repoKey
+      address = repoAddress env repoKey
       formatted = address.owner <> "/" <> address.repo
       message = appendJobIdToCommitMessage env.jobId message'
     case env.write of
@@ -708,27 +703,27 @@ handleOperation env = Cache.interpret _registryCache (Cache.handleMemory env.cac
         Log.info $ "Skipping commit to repo " <> formatted <> " because write mode is 'ReadOnly'."
         pure $ Right Git.NoChange
       CommitAs committer -> do
-        result <- Git.gitCommit { committer, address, commit: commitKeyToPaths commitKey, message } (repoPath repoKey)
+        result <- Git.gitCommit { committer, address, commit: commitKeyToPaths commitKey, message } (repoPath env repoKey)
         pure result
 
   -- | Push the repository at the given key, recording whether the push had any
   -- | effect (ie. if the repo was already up-to-date).
   push :: RepoKey -> Run _ (Either String GitResult)
   push repoKey = do
-    let address = repoAddress repoKey
+    let address = repoAddress env repoKey
     let formatted = address.owner <> "/" <> address.repo
     case env.write of
       ReadOnly -> do
         Log.info $ "Skipping push to repo " <> formatted <> " because write mode is 'ReadOnly'."
         pure $ Right Git.NoChange
       CommitAs committer -> do
-        result <- Git.gitPush { address, committer } (repoPath repoKey)
+        result <- Git.gitPush { address, committer } (repoPath env repoKey)
         pure result
 
   -- | Tag the repository at the given key at its current commit with the tag
   tag :: RepoKey -> String -> Run _ (Either String GitResult)
   tag repoKey ref = do
-    let address = repoAddress repoKey
+    let address = repoAddress env repoKey
     let formatted = address.owner <> "/" <> address.repo
     case env.write of
       ReadOnly -> do
@@ -736,7 +731,7 @@ handleOperation env = Cache.interpret _registryCache (Cache.handleMemory env.cac
         pure $ Right Git.NoChange
       CommitAs committer -> do
         result <- Except.runExcept do
-          let cwd = repoPath repoKey
+          let cwd = repoPath env repoKey
           existingTags <- Git.withGit cwd [ "tag", "--list" ] \error ->
             "Failed to list tags in local checkout " <> cwd <> ": " <> error
           if Array.elem ref $ String.split (String.Pattern "\n") existingTags then do
@@ -755,7 +750,7 @@ handleOperation env = Cache.interpret _registryCache (Cache.handleMemory env.cac
   -- | Push the repository tags at the given key to its upstream.
   pushTags :: RepoKey -> Run _ (Either String GitResult)
   pushTags repoKey = do
-    let address = repoAddress repoKey
+    let address = repoAddress env repoKey
     let formatted = address.owner <> "/" <> address.repo
     case env.write of
       ReadOnly -> do
@@ -763,7 +758,7 @@ handleOperation env = Cache.interpret _registryCache (Cache.handleMemory env.cac
         pure $ Right Git.NoChange
       CommitAs committer -> do
         result <- Except.runExcept do
-          let cwd = repoPath repoKey
+          let cwd = repoPath env repoKey
           let Git.AuthOrigin authOrigin = Git.mkAuthOrigin address committer
           output <- Git.withGit cwd [ "push", "--tags", authOrigin ] \error ->
             "Failed to push tags in local checkout " <> cwd <> ": " <> error
diff --git a/app/test/App/Effect/Registry.purs b/app/test/App/Effect/Registry.purs
index e9f2f7f0..268cf71a 100644
--- a/app/test/App/Effect/Registry.purs
+++ b/app/test/App/Effect/Registry.purs
@@ -9,8 +9,6 @@ import Node.Path as Path
 import Registry.API.V1 (JobId(..))
 import Registry.App.CLI.Git as Git
 import Registry.App.Effect.Cache as Cache
-import Registry.App.Effect.GitHub (GITHUB, GitHub)
-import Registry.App.Effect.GitHub as GitHub
 import Registry.App.Effect.Log (LOG, Log(..))
 import Registry.App.Effect.Log as Log
 import Registry.App.Effect.Registry (REGISTRY_READ, RegistryEnv, WriteMode(..))
@@ -108,16 +106,10 @@ spec = do
   runRealRegistry
     :: forall a
      . RegistryEnv
-    -> Run (REGISTRY_READ + GITHUB + LOG + EXCEPT String + AFF + EFFECT + ()) a
+    -> Run (REGISTRY_READ + LOG + EXCEPT String + AFF + EFFECT + ()) a
     -> Aff a
   runRealRegistry env =
     Registry.interpretRead (Registry.handleRead env)
-      >>> GitHub.interpret handleGitHubStub
       >>> Log.interpret (\(Log _ _ next) -> pure next)
       >>> Except.catch (\err -> Run.liftAff (Aff.throwError (Aff.error err)))
       >>> Run.runBaseAff'
-
-  -- | Stub GitHub handler — crashes if called. ReadMetadata and ReadAllMetadata
-  -- | don't use the GITHUB effect, so this should never be reached.
-  handleGitHubStub :: forall r a. GitHub a -> Run r a
-  handleGitHubStub _ = unsafeCrashWith "GITHUB effect should not be called in this test"
diff --git a/scripts/src/PackageSetUpdater.purs b/scripts/src/PackageSetUpdater.purs
index 41026a7c..d1f83370 100644
--- a/scripts/src/PackageSetUpdater.purs
+++ b/scripts/src/PackageSetUpdater.purs
@@ -6,7 +6,6 @@
 -- |   nix run .#package-set-updater -- --submit    # Actually submit to the API
 -- |
 -- | Required environment variables:
--- |   GITHUB_TOKEN - GitHub API token
 -- |   REGISTRY_API_URL - Registry API URL (default: https://registry.purescript.org)
 module Registry.Scripts.PackageSetUpdater where
 
@@ -25,21 +24,16 @@ import Effect.Class.Console as Console
 import Fetch (Method(..))
 import Fetch as Fetch
 import JSON as JSON
-import Node.Path as Path
 import Node.Process as Process
 import Registry.API.V1 as V1
 import Registry.App.CLI.Git as Git
 import Registry.App.Effect.Cache as Cache
-import Registry.App.Effect.Env (RESOURCE_ENV)
 import Registry.App.Effect.Env as Env
-import Registry.App.Effect.GitHub (GITHUB)
-import Registry.App.Effect.GitHub as GitHub
 import Registry.App.Effect.Log (LOG)
 import Registry.App.Effect.Log as Log
 import Registry.App.Effect.PackageSets as PackageSets
 import Registry.App.Effect.Registry (REGISTRY_READ)
 import Registry.App.Effect.Registry as Registry
-import Registry.Foreign.Octokit as Octokit
 import Registry.Operation (PackageSetOperation(..))
 import Registry.Operation as Operation
 import Registry.PackageName as PackageName
@@ -75,13 +69,9 @@ main = launchAff_ do
 
   Env.loadEnvFile ".env"
   resourceEnv <- Env.lookupResourceEnv
-  token <- Env.lookupRequired Env.githubToken
 
-  githubCacheRef <- Cache.newCacheRef
   registryCacheRef <- Cache.newCacheRef
-  let cache = Path.concat [ scratchDir, ".cache" ]
 
-  octokit <- Octokit.newOctokit token resourceEnv.githubApiUrl
   debouncer <- Registry.newDebouncer
 
   let
@@ -99,9 +89,7 @@ main = launchAff_ do
   runPackageSetUpdater mode resourceEnv.registryApiUrl
     # Except.runExcept
     # Registry.interpretRead (Registry.handleRead registryEnv)
-    # GitHub.interpret (GitHub.handle { octokit, cache, ref: githubCacheRef })
     # Log.interpret (Log.handleTerminal Normal)
-    # Env.runResourceEnv resourceEnv
     # Run.runBaseAff'
     >>= case _ of
       Left err -> do
@@ -109,7 +97,7 @@ main = launchAff_ do
         liftEffect $ Process.exit' 1
       Right _ -> pure unit
 
-type PackageSetUpdaterEffects = (REGISTRY_READ + GITHUB + LOG + RESOURCE_ENV + EXCEPT String + AFF + EFFECT + ())
+type PackageSetUpdaterEffects = (REGISTRY_READ + LOG + EXCEPT String + AFF + EFFECT + ())
 
 runPackageSetUpdater :: Mode -> URL -> Run PackageSetUpdaterEffects Unit
 runPackageSetUpdater mode registryApiUrl = do
diff --git a/scripts/src/VerifyIntegrity.purs b/scripts/src/VerifyIntegrity.purs
index 96c7fa5f..86833325 100644
--- a/scripts/src/VerifyIntegrity.purs
+++ b/scripts/src/VerifyIntegrity.purs
@@ -24,13 +24,11 @@ import Node.Process as Process
 import Registry.App.CLI.Git as Git
 import Registry.App.Effect.Cache as Cache
 import Registry.App.Effect.Env as Env
-import Registry.App.Effect.GitHub as GitHub
 import Registry.App.Effect.Log (LOG)
 import Registry.App.Effect.Log as Log
 import Registry.App.Effect.Registry as Registry
 import Registry.App.Effect.Storage as Storage
 import Registry.Foreign.FSExtra as FS.Extra
-import Registry.Foreign.Octokit as Octokit
 import Registry.Internal.Format as Internal.Format
 import Registry.ManifestIndex as ManifestIndex
 import Registry.PackageName as PackageName
@@ -54,12 +52,10 @@ main = launchAff_ do
 
   -- Environment
   _ <- Env.loadEnvFile ".env"
-  resourceEnv <- Env.lookupResourceEnv
 
   -- Caching
   let cache = Path.concat [ scratchDir, ".cache" ]
   FS.Extra.ensureDirectory cache
-  githubCacheRef <- Cache.newCacheRef
   registryCacheRef <- Cache.newCacheRef
 
   -- Registry
@@ -85,15 +81,10 @@ main = launchAff_ do
   log $ "Logs available at " <> logPath
 
   if localMode then do
-    token <- Env.lookupRequired Env.pacchettibottiToken
-    octokit <- Octokit.newOctokit token resourceEnv.githubApiUrl
-
     let
       interpret =
         Except.catch (\error -> Run.liftEffect (Console.log error *> Process.exit' 1))
           >>> Registry.interpretRead (Registry.handleRead registryEnv)
-          >>> GitHub.interpret (GitHub.handle { octokit, cache, ref: githubCacheRef })
-          >>> Env.runResourceEnv resourceEnv
           >>> Log.interpret (\log -> Log.handleTerminal Normal log *> Log.handleFs Verbose logPath log)
           >>> Run.runBaseAff'
 
@@ -120,16 +111,14 @@ main = launchAff_ do
         liftEffect $ Process.exit' 1
 
   else do
-    token <- Env.lookupRequired Env.pacchettibottiToken
+    resourceEnv <- Env.lookupResourceEnv
     s3 <- lift2 { key: _, secret: _ } (Env.lookupRequired Env.spacesKey) (Env.lookupRequired Env.spacesSecret)
-    octokit <- Octokit.newOctokit token resourceEnv.githubApiUrl
 
     let
       interpret =
         Except.catch (\error -> Run.liftEffect (Console.log error *> Process.exit' 1))
           >>> Registry.interpretRead (Registry.handleRead registryEnv)
           >>> Storage.interpret (Storage.handleS3 { s3, cache })
-          >>> GitHub.interpret (GitHub.handle { octokit, cache, ref: githubCacheRef })
           >>> Env.runResourceEnv resourceEnv
           >>> Log.interpret (\log -> Log.handleTerminal Normal log *> Log.handleFs Verbose logPath log)
           >>> Run.runBaseAff'

From 4a5dcc98b599802aa0f7f49fdeb4d2a49121e0ad Mon Sep 17 00:00:00 2001
From: Thomas Honeyman <hello@thomashoneyman.com>
Date: Wed, 22 Jul 2026 20:57:28 +0000
Subject: [PATCH 3/8] Add registry version check script

Amp-Thread-ID: https://ampcode.com/threads/T-019f8b91-2aa1-72c0-9046-7862234646fd

Co-authored-by: Thomas Honeyman <admin@thomashoneyman.com>
---
 nix/overlay.nix                    |  4 ++
 scripts/spago.yaml                 |  6 +++
 scripts/src/PackageSetUpdater.purs | 64 +++++++++++++++----------
 scripts/src/VersionCheck.purs      | 76 ++++++++++++++++++++++++++++++
 scripts/test/Main.purs             | 75 +++++++++++++++++++++++++++++
 spago.lock                         |  6 ++-
 6 files changed, 206 insertions(+), 25 deletions(-)
 create mode 100644 scripts/src/VersionCheck.purs
 create mode 100644 scripts/test/Main.purs

diff --git a/nix/overlay.nix b/nix/overlay.nix
index 54fa965e..c344a578 100644
--- a/nix/overlay.nix
+++ b/nix/overlay.nix
@@ -62,6 +62,10 @@ let
       module = "Registry.Scripts.PackageTransferrer";
       description = "Check for moved packages and submit transfer jobs";
     };
+    version-check = {
+      module = "Registry.Scripts.VersionCheck";
+      description = "Report registry versions pending a package set update";
+    };
     verify-integrity = {
       module = "Registry.Scripts.VerifyIntegrity";
       description = "Verify registry and registry-index consistency";
diff --git a/scripts/spago.yaml b/scripts/spago.yaml
index a3bdb19f..76d33506 100644
--- a/scripts/spago.yaml
+++ b/scripts/spago.yaml
@@ -25,3 +25,9 @@ package:
     - registry-lib
     - run
     - strings
+  test:
+    main: Test.Registry.Scripts.Main
+    dependencies:
+      - registry-test-utils
+      - spec
+      - spec-node
diff --git a/scripts/src/PackageSetUpdater.purs b/scripts/src/PackageSetUpdater.purs
index d1f83370..ab9571c7 100644
--- a/scripts/src/PackageSetUpdater.purs
+++ b/scripts/src/PackageSetUpdater.purs
@@ -48,6 +48,13 @@ data Mode = DryRun | Submit
 
 derive instance Eq Mode
 
+-- | Which registry releases should be considered for a package set update.
+-- | `AllPending` only reports upgrades to packages already in the set; adding
+-- | packages that have never appeared in a package set is a separate concern.
+data CandidateSelection
+  = RecentUploads DateTime.DateTime Hours
+  | AllPending
+
 parser :: ArgParser Mode
 parser = Arg.choose "command"
   [ Arg.flag [ "dry-run" ]
@@ -111,16 +118,9 @@ runPackageSetUpdater mode registryApiUrl = do
     Just set -> pure (Just set)
 
   for_ latestPackageSet \packageSet -> do
-    let currentPackages = (un PackageSet packageSet).packages
-
     -- Find packages uploaded in the last 24 hours
-    recentUploads <- findRecentUploads (Hours 24.0)
-    let
-      -- Filter out packages already in the set at the same or newer version
-      newOrUpdated = recentUploads # Map.filterWithKey \name version ->
-        case Map.lookup name currentPackages of
-          Nothing -> true -- new package
-          Just currentVersion -> version > currentVersion -- upgrade
+    now <- nowUTC
+    newOrUpdated <- findPackageSetCandidates (RecentUploads now (Hours 24.0)) packageSet
 
     if Map.isEmpty newOrUpdated then
       Log.info "No new packages for package set update."
@@ -175,23 +175,39 @@ runPackageSetUpdater mode registryApiUrl = do
               Right { jobId } -> do
                 Log.info $ "Submitted package set job " <> unwrap jobId
 
--- | Find the latest version of each package uploaded within the time limit
-findRecentUploads :: Hours -> Run PackageSetUpdaterEffects (Map PackageName Version)
-findRecentUploads limit = do
+-- | Find the latest eligible registry version for each package relative to the
+-- | current package set.
+findPackageSetCandidates
+  :: forall r
+   . CandidateSelection
+  -> PackageSet
+  -> Run (REGISTRY_READ + EXCEPT String + r) (Map PackageName Version)
+findPackageSetCandidates selection packageSet = do
   allMetadata <- Registry.readAllMetadata
-  now <- nowUTC
-
+  pure $ selectPackageSetCandidates selection packageSet allMetadata
+
+-- | Select package set candidates in one traversal of registry metadata.
+selectPackageSetCandidates
+  :: CandidateSelection
+  -> PackageSet
+  -> Map PackageName Metadata
+  -> Map PackageName Version
+selectPackageSetCandidates selection (PackageSet packageSet) = Map.mapMaybeWithKey \name (Metadata metadata) -> do
   let
-    getLatestRecentVersion :: Metadata -> Maybe Version
-    getLatestRecentVersion (Metadata metadata) = do
-      let
-        recentVersions = Array.catMaybes $ flip map (Map.toUnfoldable metadata.published)
-          \(Tuple version { publishedTime }) ->
-            if (DateTime.diff now publishedTime) <= limit then Just version else Nothing
-      Array.last $ Array.sort recentVersions
-
-  pure $ Map.fromFoldable $ Array.catMaybes $ flip map (Map.toUnfoldable allMetadata) \(Tuple name metadata) ->
-    map (Tuple name) $ getLatestRecentVersion metadata
+    eligibleVersions = Array.mapMaybe
+      ( \(Tuple version { publishedTime }) -> case selection of
+          RecentUploads now limit
+            | DateTime.diff now publishedTime <= limit -> Just version
+          RecentUploads _ _ -> Nothing
+          AllPending -> Just version
+      )
+      (Map.toUnfoldable metadata.published)
+  latestVersion <- Array.last $ Array.sort eligibleVersions
+  case Map.lookup name packageSet.packages of
+    Just currentVersion
+      | latestVersion > currentVersion -> Just latestVersion
+    Nothing | RecentUploads _ _ <- selection -> Just latestVersion
+    _ -> Nothing
 
 -- | Submit a package set job to the registry API
 submitPackageSetJob :: String -> Operation.PackageSetUpdateRequest -> Aff (Either String V1.JobCreatedResponse)
diff --git a/scripts/src/VersionCheck.purs b/scripts/src/VersionCheck.purs
new file mode 100644
index 00000000..6f30be68
--- /dev/null
+++ b/scripts/src/VersionCheck.purs
@@ -0,0 +1,76 @@
+-- | Report the latest registry versions that are newer than their versions in
+-- | the latest package set.
+-- |
+-- | Packages that have never appeared in a package set are intentionally not
+-- | included; discovering those packages is tracked as separate follow-up work.
+-- |
+-- | Run via Nix:
+-- |   nix run .#version-check
+module Registry.Scripts.VersionCheck where
+
+import Registry.App.Prelude
+
+import Data.Map as Map
+import Effect.Class.Console as Console
+import Node.Process as Process
+import Registry.App.CLI.Git as Git
+import Registry.App.Effect.Cache as Cache
+import Registry.App.Effect.Log (LOG)
+import Registry.App.Effect.Log as Log
+import Registry.App.Effect.Registry (REGISTRY_READ)
+import Registry.App.Effect.Registry as Registry
+import Registry.PackageName as PackageName
+import Registry.Scripts.PackageSetUpdater as PackageSetUpdater
+import Registry.Version as Version
+import Run (AFF, EFFECT, Run)
+import Run as Run
+import Run.Except (EXCEPT)
+import Run.Except as Except
+
+main :: Effect Unit
+main = launchAff_ do
+  registryCacheRef <- Cache.newCacheRef
+  debouncer <- Registry.newDebouncer
+
+  let
+    registryEnv :: Registry.RegistryEnv
+    registryEnv =
+      { jobId: Nothing
+      , pull: Git.Autostash
+      , write: Registry.ReadOnly
+      , repos: Registry.defaultRepos
+      , workdir: scratchDir
+      , debouncer
+      , cacheRef: registryCacheRef
+      }
+
+  result <- runVersionCheck
+    # Except.runExcept
+    # Registry.interpretRead (Registry.handleRead registryEnv)
+    # Log.interpret (Log.handleTerminal Normal)
+    # Run.runBaseAff'
+
+  case result of
+    Left err -> do
+      Console.error $ "Error: " <> err
+      liftEffect $ Process.exit' 1
+    Right _ -> pure unit
+
+type VersionCheckEffects = (REGISTRY_READ + LOG + EXCEPT String + AFF + EFFECT + ())
+
+runVersionCheck :: Run VersionCheckEffects (Map PackageName Version)
+runVersionCheck = do
+  Log.info "Registry Version Check: checking for pending package set updates..."
+  Registry.readLatestPackageSet >>= case _ of
+    Nothing -> do
+      Log.warn "No package set found, skipping version check."
+      pure Map.empty
+    Just packageSet -> do
+      pending <- PackageSetUpdater.findPackageSetCandidates PackageSetUpdater.AllPending packageSet
+      if Map.isEmpty pending then
+        Log.info "No package versions are pending a package set update."
+      else do
+        Log.info $ "Found " <> show (Map.size pending) <> " package versions pending a package set update:"
+        for_ (Map.toUnfoldable pending :: Array _) \(Tuple name version) ->
+          Log.info $ "  - " <> PackageName.print name <> "@" <> Version.print version
+      pure pending
diff --git a/scripts/test/Main.purs b/scripts/test/Main.purs
new file mode 100644
index 00000000..9bacfbcb
--- /dev/null
+++ b/scripts/test/Main.purs
@@ -0,0 +1,75 @@
+module Test.Registry.Scripts.Main (main) where
+
+import Registry.App.Prelude
+
+import Data.DateTime (DateTime)
+import Data.Map as Map
+import Data.Time.Duration (Hours(..))
+import Registry.Metadata (Metadata)
+import Registry.Metadata as Metadata
+import Registry.PackageName (PackageName)
+import Registry.PackageSet (PackageSet)
+import Registry.PackageSet as PackageSet
+import Registry.Scripts.PackageSetUpdater as PackageSetUpdater
+import Registry.Test.Assert as Assert
+import Registry.Test.Utils as Utils
+import Registry.Version (Version)
+import Test.Spec as Spec
+import Test.Spec.Reporter.Console (consoleReporter)
+import Test.Spec.Runner.Node (runSpecAndExitProcess)
+
+main :: Effect Unit
+main = runSpecAndExitProcess [ consoleReporter ] do
+  Spec.describe "PackageSetUpdater candidate selection" do
+    Spec.it "finds all newer versions of packages already in the package set" do
+      let
+        metadata = Map.fromFoldable
+          [ Utils.unsafeMetadata "prelude" [ Tuple "1.0.0" [ "0.15.10" ], Tuple "2.0.0" [ "0.15.10" ] ]
+          , Utils.unsafeMetadata "effect" [ Tuple "2.0.0" [ "0.15.10" ] ]
+          , Utils.unsafeMetadata "older" [ Tuple "1.0.0" [ "0.15.10" ] ]
+          , Utils.unsafeMetadata "never-in-set" [ Tuple "1.0.0" [ "0.15.10" ] ]
+          ]
+        packageSet = mkPackageSet $ Map.fromFoldable
+          [ Tuple (Utils.unsafePackageName "prelude") (Utils.unsafeVersion "1.0.0")
+          , Tuple (Utils.unsafePackageName "effect") (Utils.unsafeVersion "2.0.0")
+          , Tuple (Utils.unsafePackageName "older") (Utils.unsafeVersion "2.0.0")
+          ]
+        expected = Map.singleton (Utils.unsafePackageName "prelude") (Utils.unsafeVersion "2.0.0")
+
+      PackageSetUpdater.selectPackageSetCandidates PackageSetUpdater.AllPending packageSet metadata
+        `Assert.shouldEqual` expected
+
+    Spec.it "preserves recent candidate selection for new packages and upgrades" do
+      let
+        oldTime = Utils.unsafeDateTime "2023-12-30T00:00:00.000Z"
+        now = Utils.unsafeDateTime "2024-01-02T00:00:00.000Z"
+        metadata = Map.fromFoldable
+          [ Utils.unsafeMetadata "prelude" [ Tuple "1.0.0" [ "0.15.10" ], Tuple "2.0.0" [ "0.15.10" ] ]
+          , Utils.unsafeMetadata "effect" [ Tuple "1.0.0" [ "0.15.10" ] ]
+          , withPublishedTime oldTime $ Utils.unsafeMetadata "old-upload" [ Tuple "1.0.0" [ "0.15.10" ] ]
+          , Utils.unsafeMetadata "new-package" [ Tuple "1.0.0" [ "0.15.10" ] ]
+          ]
+        packageSet = mkPackageSet $ Map.fromFoldable
+          [ Tuple (Utils.unsafePackageName "prelude") (Utils.unsafeVersion "1.0.0")
+          , Tuple (Utils.unsafePackageName "effect") (Utils.unsafeVersion "1.0.0")
+          ]
+        expected = Map.fromFoldable
+          [ Tuple (Utils.unsafePackageName "prelude") (Utils.unsafeVersion "2.0.0")
+          , Tuple (Utils.unsafePackageName "new-package") (Utils.unsafeVersion "1.0.0")
+          ]
+
+      PackageSetUpdater.selectPackageSetCandidates (PackageSetUpdater.RecentUploads now (Hours 24.0)) packageSet metadata
+        `Assert.shouldEqual` expected
+
+mkPackageSet :: Map PackageName Version -> PackageSet
+mkPackageSet packages = PackageSet.PackageSet
+  { version: Utils.unsafeVersion "1.0.0"
+  , compiler: Utils.unsafeVersion "0.15.10"
+  , published: Utils.unsafeDate "2024-01-01"
+  , packages
+  }
+
+withPublishedTime :: forall a. DateTime -> Tuple a Metadata -> Tuple a Metadata
+withPublishedTime publishedTime (Tuple name (Metadata.Metadata metadata)) =
+  Tuple name $ Metadata.Metadata $ metadata
+    { published = map (_ { publishedTime = publishedTime }) metadata.published }
diff --git a/spago.lock b/spago.lock
index d3b93a36..98749509 100644
--- a/spago.lock
+++ b/spago.lock
@@ -291,7 +291,11 @@
           ]
         },
         "test": {
-          "dependencies": []
+          "dependencies": [
+            "registry-test-utils",
+            "spec",
+            "spec-node"
+          ]
         }
       },
       "registry-test-utils": {

From 8acb229babe9d8da643776d7e90f48b6540225da Mon Sep 17 00:00:00 2001
From: Thomas Honeyman <hello@thomashoneyman.com>
Date: Wed, 22 Jul 2026 21:15:50 +0000
Subject: [PATCH 4/8] Match script interpreter formatting

Amp-Thread-ID: https://ampcode.com/threads/T-019f8b91-2aa1-72c0-9046-7862234646fd

Co-authored-by: Thomas Honeyman <admin@thomashoneyman.com>
---
 scripts/src/VersionCheck.purs | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/scripts/src/VersionCheck.purs b/scripts/src/VersionCheck.purs
index 6f30be68..a89ccbfc 100644
--- a/scripts/src/VersionCheck.purs
+++ b/scripts/src/VersionCheck.purs
@@ -44,17 +44,16 @@ main = launchAff_ do
       , cacheRef: registryCacheRef
       }
 
-  result <- runVersionCheck
+  runVersionCheck
     # Except.runExcept
     # Registry.interpretRead (Registry.handleRead registryEnv)
     # Log.interpret (Log.handleTerminal Normal)
     # Run.runBaseAff'
-
-  case result of
-    Left err -> do
-      Console.error $ "Error: " <> err
-      liftEffect $ Process.exit' 1
-    Right _ -> pure unit
+    >>= case _ of
+      Left err -> do
+        Console.error $ "Error: " <> err
+        liftEffect $ Process.exit' 1
+      Right _ -> pure unit
 
 type VersionCheckEffects = (REGISTRY_READ + LOG + EXCEPT String + AFF + EFFECT + ())
 

From d283822785f18302d0d3faf2a5c5ca80086ced80 Mon Sep 17 00:00:00 2001
From: Thomas Honeyman <hello@thomashoneyman.com>
Date: Mon, 27 Jul 2026 19:12:15 +0000
Subject: [PATCH 5/8] Plan and report package set updates

---
 .github/workflows/version-check.yml |  62 +++
 scripts/src/VersionCheck.purs       | 560 ++++++++++++++++++++++++++--
 scripts/test/Main.purs              | 128 +++++++
 3 files changed, 729 insertions(+), 21 deletions(-)
 create mode 100644 .github/workflows/version-check.yml

diff --git a/.github/workflows/version-check.yml b/.github/workflows/version-check.yml
new file mode 100644
index 00000000..e1a9b5f1
--- /dev/null
+++ b/.github/workflows/version-check.yml
@@ -0,0 +1,62 @@
+name: Weekly package set version check
+
+on:
+  schedule:
+    - cron: '0 6 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+concurrency:
+  group: weekly-package-set-version-check
+  cancel-in-progress: false
+
+jobs:
+  version-check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 90
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install Nix
+        uses: DeterminateSystems/determinate-nix-action@v3
+
+      - name: Setup Nix cache
+        uses: DeterminateSystems/magic-nix-cache-action@v14
+        with:
+          use-flakehub: false
+
+      - name: Plan and verify pending package set updates
+        run: nix run .#version-check -- --verify --output version-check.json --markdown version-check.md
+
+      - name: Upload report
+        uses: actions/upload-artifact@v4
+        with:
+          name: package-set-version-check
+          path: |
+            version-check.json
+            version-check.md
+
+      - name: Update rolling report issue
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPOSITORY: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+
+          title='Weekly package set version report'
+          issue_number=$(
+            gh issue list --repo "$REPOSITORY" --state open --search "$title in:title" --limit 100 --json number,title \
+              | jq -r --arg title "$title" '.[] | select(.title == $title) | .number' \
+              | sed -n '1p'
+          )
+
+          if [[ -n "$issue_number" ]]; then
+            gh issue edit "$issue_number" --repo "$REPOSITORY" --body-file version-check.md
+          else
+            gh issue create --repo "$REPOSITORY" --title "$title" --body-file version-check.md
+          fi
diff --git a/scripts/src/VersionCheck.purs b/scripts/src/VersionCheck.purs
index a89ccbfc..eec62d62 100644
--- a/scripts/src/VersionCheck.purs
+++ b/scripts/src/VersionCheck.purs
@@ -1,34 +1,104 @@
--- | Report the latest registry versions that are newer than their versions in
--- | the latest package set.
+-- | Report registry versions newer than those in the latest package set and
+-- | plan a compatible set of upgrades.
 -- |
 -- | Packages that have never appeared in a package set are intentionally not
 -- | included; discovering those packages is tracked as separate follow-up work.
+-- | Planning is conservative: a release is eligible only after its metadata
+-- | records a successful build with the package set compiler.
+-- |
+-- | Each pending package is a variable whose choices are its current version
+-- | and all eligible newer versions. A bounded branch-and-bound search visits
+-- | newer choices first and maximizes, in order, the number of upgraded packages
+-- | and their cumulative freshness. Partial dependency-range checks prune
+-- | impossible branches. Existing range mismatches are tolerated only when both
+-- | ends of the dependency edge remain unchanged because historical package sets
+-- | can contain stale declared bounds despite having compiled successfully.
+-- |
+-- | The search has a fixed node budget so the weekly report cannot hang on a
+-- | pathological candidate graph, and any truncation is explicit in the report.
+-- | The optional verification atomically compiles the exact planned payload but
+-- | never publishes it.
 -- |
 -- | Run via Nix:
 -- |   nix run .#version-check
+-- |   nix run .#version-check -- --verify --output report.json --markdown report.md
 module Registry.Scripts.VersionCheck where
 
 import Registry.App.Prelude
 
+import ArgParse.Basic (ArgParser)
+import ArgParse.Basic as Arg
+import Data.Array as Array
+import Data.Codec.JSON as CJ
+import Data.Codec.JSON.Common as CJ.Common
+import Data.Codec.JSON.Record as CJ.Record
+import Data.DateTime (DateTime)
+import Data.DateTime as DateTime
+import Data.Foldable as Foldable
+import Data.Int as Int
 import Data.Map as Map
+import Data.Set as Set
+import Data.String as String
+import Data.Time.Duration (Days(..))
 import Effect.Class.Console as Console
+import Node.FS.Aff as FS.Aff
+import Node.Path as Path
 import Node.Process as Process
 import Registry.App.CLI.Git as Git
 import Registry.App.Effect.Cache as Cache
+import Registry.App.Effect.Env (RESOURCE_ENV)
+import Registry.App.Effect.Env as Env
 import Registry.App.Effect.Log (LOG)
 import Registry.App.Effect.Log as Log
+import Registry.App.Effect.PackageSets (PACKAGE_SETS)
+import Registry.App.Effect.PackageSets as PackageSets
 import Registry.App.Effect.Registry (REGISTRY_READ)
 import Registry.App.Effect.Registry as Registry
+import Registry.App.Effect.Storage (STORAGE)
+import Registry.App.Effect.Storage as Storage
+import Registry.Foreign.FSExtra as FS.Extra
+import Registry.Internal.Codec as Internal.Codec
+import Registry.Manifest (Manifest(..))
+import Registry.ManifestIndex (ManifestIndex)
+import Registry.ManifestIndex as ManifestIndex
+import Registry.Metadata (Metadata(..))
+import Registry.PackageName (PackageName)
 import Registry.PackageName as PackageName
-import Registry.Scripts.PackageSetUpdater as PackageSetUpdater
+import Registry.PackageSet (PackageSet(..))
+import Registry.Range (Range)
+import Registry.Range as Range
+import Registry.Version (Version)
 import Registry.Version as Version
 import Run (AFF, EFFECT, Run)
 import Run as Run
 import Run.Except (EXCEPT)
 import Run.Except as Except
 
+type Options =
+  { markdown :: Maybe FilePath
+  , output :: Maybe FilePath
+  , verify :: Boolean
+  }
+
+parser :: ArgParser Options
+parser = ado
+  verify <- Arg.flag [ "--verify" ] "Atomically compile the planned update without publishing it." # Arg.boolean # Arg.default false
+  output <- Arg.argument [ "--output" ] "Write the structured report as JSON." # Arg.optional
+  markdown <- Arg.argument [ "--markdown" ] "Write the human-readable report as Markdown." # Arg.optional
+  in { markdown, output, verify }
+
 main :: Effect Unit
 main = launchAff_ do
+  args <- Array.drop 2 <$> liftEffect Process.argv
+  let description = "Report, plan, and optionally verify registry versions pending a package set update."
+  options <- case Arg.parseArgs "version-check" description parser args of
+    Left err -> Console.log (Arg.printArgError err) *> liftEffect (Process.exit' 1)
+    Right parsed -> pure parsed
+
+  resourceEnv <- Env.lookupResourceEnv
+
+  let cache = Path.concat [ scratchDir, ".cache" ]
+  FS.Extra.ensureDirectory cache
   registryCacheRef <- Cache.newCacheRef
   debouncer <- Registry.newDebouncer
 
@@ -44,32 +114,480 @@ main = launchAff_ do
       , cacheRef: registryCacheRef
       }
 
-  runVersionCheck
+  runVersionCheck options.verify
+    # PackageSets.interpret (PackageSets.handle { workdir: scratchDir })
     # Except.runExcept
     # Registry.interpretRead (Registry.handleRead registryEnv)
+    # Storage.interpret (Storage.handleReadOnly cache)
+    # Env.runResourceEnv resourceEnv
     # Log.interpret (Log.handleTerminal Normal)
     # Run.runBaseAff'
     >>= case _ of
       Left err -> do
         Console.error $ "Error: " <> err
         liftEffect $ Process.exit' 1
-      Right _ -> pure unit
+      Right report -> do
+        let markdown = renderMarkdown report
+        Console.log markdown
+        for_ options.output \path -> writeJsonFile reportCodec path report
+        for_ options.markdown \path -> FS.Aff.writeTextFile UTF8 path (markdown <> "\n")
+
+type Incompatibility =
+  { dependency :: PackageName
+  , package :: PackageName
+  , packageDirectDependants :: Int
+  , packageTransitiveDependants :: Int
+  , range :: Range
+  , selectedVersion :: Maybe Version
+  , version :: Version
+  }
+
+type PendingPackage =
+  { blockedBy :: Array Incompatibility
+  , blockers :: Array Incompatibility
+  , candidate :: Version
+  , candidateCompilerCompatible :: Boolean
+  , candidatePublished :: DateTime
+  , current :: Version
+  , directDependants :: Int
+  , name :: PackageName
+  , planned :: Maybe Version
+  , staleDays :: Int
+  , staleSince :: DateTime
+  , transitiveDependants :: Int
+  }
+
+type Plan =
+  { error :: Maybe String
+  , packages :: Map PackageName Version
+  , searchTruncated :: Boolean
+  }
+
+type Verification =
+  { error :: Maybe String
+  , status :: String
+  }
+
+type Report =
+  { compiler :: Version
+  , generatedAt :: DateTime
+  , latestIncompatibilities :: Array Incompatibility
+  , packageSet :: Version
+  , pending :: Array PendingPackage
+  , plan :: Plan
+  , verification :: Verification
+  }
+
+incompatibilityCodec :: CJ.Codec Incompatibility
+incompatibilityCodec = CJ.named "VersionCheckIncompatibility" $ CJ.Record.object
+  { dependency: PackageName.codec
+  , package: PackageName.codec
+  , packageDirectDependants: CJ.int
+  , packageTransitiveDependants: CJ.int
+  , range: Range.codec
+  , selectedVersion: CJ.Common.nullable Version.codec
+  , version: Version.codec
+  }
 
-type VersionCheckEffects = (REGISTRY_READ + LOG + EXCEPT String + AFF + EFFECT + ())
+pendingPackageCodec :: CJ.Codec PendingPackage
+pendingPackageCodec = CJ.named "VersionCheckPendingPackage" $ CJ.Record.object
+  { blockedBy: CJ.array incompatibilityCodec
+  , blockers: CJ.array incompatibilityCodec
+  , candidate: Version.codec
+  , candidateCompilerCompatible: CJ.boolean
+  , candidatePublished: Internal.Codec.iso8601DateTime
+  , current: Version.codec
+  , directDependants: CJ.int
+  , name: PackageName.codec
+  , planned: CJ.Common.nullable Version.codec
+  , staleDays: CJ.int
+  , staleSince: Internal.Codec.iso8601DateTime
+  , transitiveDependants: CJ.int
+  }
 
-runVersionCheck :: Run VersionCheckEffects (Map PackageName Version)
-runVersionCheck = do
+planCodec :: CJ.Codec Plan
+planCodec = CJ.named "VersionCheckPlan" $ CJ.Record.object
+  { error: CJ.Common.nullable CJ.string
+  , packages: Internal.Codec.packageMap Version.codec
+  , searchTruncated: CJ.boolean
+  }
+
+verificationCodec :: CJ.Codec Verification
+verificationCodec = CJ.named "VersionCheckVerification" $ CJ.Record.object
+  { error: CJ.Common.nullable CJ.string
+  , status: CJ.string
+  }
+
+reportCodec :: CJ.Codec Report
+reportCodec = CJ.named "VersionCheckReport" $ CJ.Record.object
+  { compiler: Version.codec
+  , generatedAt: Internal.Codec.iso8601DateTime
+  , latestIncompatibilities: CJ.array incompatibilityCodec
+  , packageSet: Version.codec
+  , pending: CJ.array pendingPackageCodec
+  , plan: planCodec
+  , verification: verificationCodec
+  }
+
+type Candidate =
+  { candidate :: Version
+  , candidatePublished :: DateTime
+  , compatibleVersions :: Array Version
+  , current :: Version
+  , name :: PackageName
+  , staleSince :: DateTime
+  }
+
+type Choice =
+  { freshness :: Int
+  , upgrade :: Int
+  , version :: Version
+  }
+
+type PlannerVariable =
+  { choices :: Array Choice
+  , name :: PackageName
+  }
+
+type PlanScore =
+  { freshness :: Int
+  , upgrades :: Int
+  }
+
+type ScoredPlan =
+  { packages :: Map PackageName Version
+  , score :: PlanScore
+  }
+
+type SearchState =
+  { best :: Maybe ScoredPlan
+  , remainingNodes :: Int
+  , truncated :: Boolean
+  }
+
+type VersionCheckEffects = (REGISTRY_READ + PACKAGE_SETS + STORAGE + RESOURCE_ENV + LOG + EXCEPT String + AFF + EFFECT + ())
+
+runVersionCheck :: Boolean -> Run VersionCheckEffects Report
+runVersionCheck verify = do
   Log.info "Registry Version Check: checking for pending package set updates..."
-  Registry.readLatestPackageSet >>= case _ of
-    Nothing -> do
-      Log.warn "No package set found, skipping version check."
-      pure Map.empty
-    Just packageSet -> do
-      pending <- PackageSetUpdater.findPackageSetCandidates PackageSetUpdater.AllPending packageSet
-      if Map.isEmpty pending then
-        Log.info "No package versions are pending a package set update."
-      else do
-        Log.info $ "Found " <> show (Map.size pending) <> " package versions pending a package set update:"
-        for_ (Map.toUnfoldable pending :: Array _) \(Tuple name version) ->
-          Log.info $ "  - " <> PackageName.print name <> "@" <> Version.print version
-      pure pending
+  packageSet <- Registry.readLatestPackageSet >>= case _ of
+    Nothing -> Except.throw "No package set found."
+    Just found -> pure found
+  metadata <- Registry.readAllMetadata
+  manifests <- Registry.readAllManifests
+  generatedAt <- nowUTC
+  let initial = buildReport generatedAt packageSet metadata manifests
+  verification <- verifyPlan verify packageSet initial.plan
+  let report = initial { verification = verification }
+  Log.info $ "Found " <> show (Array.length report.pending) <> " package versions pending a package set update."
+  pure report
+
+verifyPlan
+  :: forall r
+   . Boolean
+  -> PackageSet
+  -> Plan
+  -> Run (PACKAGE_SETS + LOG + EXCEPT String + AFF + EFFECT + r) Verification
+verifyPlan verify packageSet plan
+  | not verify = pure { error: Nothing, status: "not-run" }
+  | Just error <- plan.error = pure { error: Just error, status: "failed" }
+  | Map.isEmpty plan.packages = pure { error: Nothing, status: "not-needed" }
+  | otherwise = do
+      Log.info $ "Atomically compiling " <> show (Map.size plan.packages) <> " planned package updates..."
+      Except.runExcept (PackageSets.upgradeAtomic packageSet (un PackageSet packageSet).compiler (map PackageSets.Update plan.packages)) >>= case _ of
+        Left error -> pure { error: Just error, status: "failed" }
+        Right (Left error) -> pure { error: Just error, status: "failed" }
+        Right (Right _) -> pure { error: Nothing, status: "verified" }
+
+buildReport :: DateTime -> PackageSet -> Map PackageName Metadata -> ManifestIndex -> Report
+buildReport generatedAt packageSet@(PackageSet set) metadata manifests = do
+  let candidates = findCandidates set.compiler set.packages metadata manifests
+  let latest = Map.fromFoldable $ candidates <#> \candidate -> Tuple candidate.name candidate.candidate
+  let proposed = Map.union latest set.packages
+  let
+    plan = case planPackageSet packageSet metadata manifests of
+      Left error -> { error: Just error, packages: Map.empty, searchTruncated: false }
+      Right { packages, searchTruncated } -> { error: Nothing, packages, searchTruncated }
+  let planned = Map.union plan.packages set.packages
+  let latestIncompatibilities = findIncompatibilities set.packages proposed manifests
+  let
+    pending = candidates <#> \candidate -> do
+      let direct = directDependants set.packages manifests candidate.name
+      let transitive = transitiveDependants set.packages manifests candidate.name
+      let candidateIncompatibilities = findIncompatibilities set.packages (Map.insert candidate.name candidate.candidate planned) manifests
+      { blockedBy: Array.filter (_.package >>> eq candidate.name) candidateIncompatibilities
+      , blockers: Array.filter (_.dependency >>> eq candidate.name) candidateIncompatibilities
+      , candidate: candidate.candidate
+      , candidateCompilerCompatible: Array.elem candidate.candidate candidate.compatibleVersions
+      , candidatePublished: candidate.candidatePublished
+      , current: candidate.current
+      , directDependants: Array.length direct
+      , name: candidate.name
+      , planned: Map.lookup candidate.name plan.packages
+      , staleDays: daysBetween candidate.staleSince generatedAt
+      , staleSince: candidate.staleSince
+      , transitiveDependants: Array.length transitive
+      }
+  { compiler: set.compiler
+  , generatedAt
+  , latestIncompatibilities
+  , packageSet: set.version
+  , pending
+  , plan
+  , verification: { error: Nothing, status: "not-run" }
+  }
+
+-- Candidate versions are restricted to releases known to compile with the
+-- package set compiler and present in the manifest index. The report still
+-- retains the actual latest release so incompatible latest releases stay
+-- visible even when the planner chooses an intermediate version.
+findCandidates
+  :: Version
+  -> Map PackageName Version
+  -> Map PackageName Metadata
+  -> ManifestIndex
+  -> Array Candidate
+findCandidates compiler packages metadata manifests = Array.mapMaybe toCandidate (Map.toUnfoldable packages)
+  where
+  toCandidate (Tuple name current) = do
+    Metadata packageMetadata <- Map.lookup name metadata
+    let newer = Array.filter (fst >>> (_ > current)) (Map.toUnfoldable packageMetadata.published)
+    latest@(Tuple candidate candidateMetadata) <- Array.last $ Array.sortBy (comparing fst) newer
+    let Tuple _ staleMetadata = Foldable.minimumBy (comparing (_.publishedTime <<< snd)) newer # fromMaybe latest
+    let staleSince = staleMetadata.publishedTime
+    let
+      compatibleVersions = newer
+        # Array.mapMaybe
+            ( \(Tuple version published) -> do
+                guard $ Foldable.elem compiler published.compilers
+                _ <- ManifestIndex.lookup name version manifests
+                pure version
+            )
+        # Array.sort
+    pure
+      { candidate
+      , candidatePublished: candidateMetadata.publishedTime
+      , compatibleVersions
+      , current
+      , name
+      , staleSince
+      }
+
+-- Maximize the number of upgraded packages, then their cumulative freshness,
+-- while satisfying the exact selected dependency versions. Existing range
+-- mismatches are tolerated only when both ends of that dependency edge remain
+-- unchanged; this is necessary because package sets prove compatibility by
+-- compilation and some historical manifests have stale bounds.
+planPackageSet
+  :: PackageSet
+  -> Map PackageName Metadata
+  -> ManifestIndex
+  -> Either String { packages :: Map PackageName Version, searchTruncated :: Boolean }
+planPackageSet (PackageSet set) metadata manifests = do
+  let candidates = findCandidates set.compiler set.packages metadata manifests
+  let variables = Array.mapMaybe toVariable candidates
+  let fixed = Foldable.foldl (flip Map.delete) set.packages (map _.name variables)
+  unless (completePlanIsValid manifests set.packages set.packages) do
+    Left "The current package set is missing a manifest or one of its declared dependencies."
+  let search = searchPlan manifests set.packages variables fixed
+  result <- note "No compatible package set update could be planned without introducing new dependency-range violations." search.best
+  pure
+    { packages: Map.filterWithKey
+        (\name version -> maybe false (version > _) (Map.lookup name set.packages))
+        result.packages
+    , searchTruncated: search.truncated
+    }
+  where
+  toVariable candidate = do
+    guard $ not (Array.null candidate.compatibleVersions)
+    let
+      choices =
+        [ { freshness: 0, upgrade: 0, version: candidate.current } ]
+          <> Array.mapWithIndex
+            (\index version -> { freshness: index + 1, upgrade: 1, version })
+            candidate.compatibleVersions
+    pure { choices, name: candidate.name }
+
+-- Branch-and-bound visits newest choices first and prunes a branch when its
+-- best possible score cannot improve on the best complete plan already found.
+-- The node budget keeps a pathological dependency graph from hanging the
+-- weekly report; a truncated plan is reported but not automatically submitted.
+searchPlan
+  :: ManifestIndex
+  -> Map PackageName Version
+  -> Array PlannerVariable
+  -> Map PackageName Version
+  -> { best :: Maybe ScoredPlan, truncated :: Boolean }
+searchPlan manifests baseline variables fixed = do
+  let baselinePlan = { packages: baseline, score: { freshness: 0, upgrades: 0 } }
+  let result = go 0 fixed { freshness: 0, upgrades: 0 } { best: Just baselinePlan, remainingNodes: 50_000, truncated: false }
+  { best: result.best, truncated: result.truncated }
+  where
+  go :: Int -> Map PackageName Version -> PlanScore -> SearchState -> SearchState
+  go offset selected score state
+    | state.remainingNodes <= 0 = state { truncated = true }
+    | otherwise = do
+        let nextState = state { remainingNodes = state.remainingNodes - 1 }
+        let remaining = Array.drop offset variables
+        let potential = addScores score (maximumRemainingScore remaining)
+        if maybe false (not <<< betterScore potential <<< _.score) nextState.best then
+          nextState
+        else case Array.index variables offset of
+          Nothing ->
+            if completePlanIsValid manifests baseline selected then nextState { best = chooseBetter { packages: selected, score } nextState.best } else nextState
+          Just variable ->
+            Array.foldl
+              ( \currentState choice -> do
+                  let nextSelected = Map.insert variable.name choice.version selected
+                  let nextRemaining = Array.drop (offset + 1) variables
+                  let nextScore = addScores score { freshness: choice.freshness, upgrades: choice.upgrade }
+                  if partialPlanIsPossible manifests baseline nextSelected nextRemaining then
+                    go (offset + 1) nextSelected nextScore currentState
+                  else
+                    currentState
+              )
+              nextState
+              (Array.reverse variable.choices)
+
+maximumRemainingScore :: Array PlannerVariable -> PlanScore
+maximumRemainingScore = Array.foldl addMaximum { freshness: 0, upgrades: 0 }
+  where
+  addMaximum score variable = case Array.last variable.choices of
+    Nothing -> score
+    Just choice -> addScores score { freshness: choice.freshness, upgrades: choice.upgrade }
+
+addScores :: PlanScore -> PlanScore -> PlanScore
+addScores a b =
+  { freshness: a.freshness + b.freshness
+  , upgrades: a.upgrades + b.upgrades
+  }
+
+betterScore :: PlanScore -> PlanScore -> Boolean
+betterScore a b = a.upgrades > b.upgrades || (a.upgrades == b.upgrades && a.freshness > b.freshness)
+
+chooseBetter :: ScoredPlan -> Maybe ScoredPlan -> Maybe ScoredPlan
+chooseBetter candidate = case _ of
+  Nothing -> Just candidate
+  Just current | betterScore candidate.score current.score -> Just candidate
+  current -> current
+
+-- Check selected manifests against exact selected dependency versions. For an
+-- unselected dependency, at least one of its remaining choices must satisfy
+-- the range (or preserve an unchanged baseline mismatch).
+partialPlanIsPossible :: ManifestIndex -> Map PackageName Version -> Map PackageName Version -> Array PlannerVariable -> Boolean
+partialPlanIsPossible manifests baseline selected remaining = all manifestIsPossible (Map.toUnfoldable selected :: Array (Tuple PackageName Version))
+  where
+  remainingChoices = Map.fromFoldable $ remaining <#> \variable -> Tuple variable.name variable.choices
+
+  manifestIsPossible (Tuple name version) = fromMaybe false do
+    Manifest manifest <- ManifestIndex.lookup name version manifests
+    pure $ all (dependencyIsPossible name version) (Map.toUnfoldable manifest.dependencies :: Array (Tuple PackageName Range))
+
+  dependencyIsPossible name packageVersion (Tuple dependency range) = case Map.lookup dependency selected of
+    Just dependencyVersion -> choiceIsCompatible name packageVersion dependency range dependencyVersion
+    Nothing -> fromMaybe false do
+      choices <- Map.lookup dependency remainingChoices
+      pure $ any (choiceIsCompatible name packageVersion dependency range <<< _.version) choices
+
+  choiceIsCompatible name packageVersion dependency range dependencyVersion =
+    Range.includes range dependencyVersion
+      ||
+        ( Map.lookup name baseline == Just packageVersion
+            && Map.lookup dependency baseline
+            == Just dependencyVersion
+        )
+
+completePlanIsValid :: ManifestIndex -> Map PackageName Version -> Map PackageName Version -> Boolean
+completePlanIsValid manifests baseline selected = partialPlanIsPossible manifests baseline selected []
+
+findIncompatibilities :: Map PackageName Version -> Map PackageName Version -> ManifestIndex -> Array Incompatibility
+findIncompatibilities baseline selected manifests = do
+  Tuple package version <- Map.toUnfoldable selected
+  Manifest manifest <- Array.fromFoldable $ ManifestIndex.lookup package version manifests
+  Tuple dependency range <- Map.toUnfoldable manifest.dependencies
+  let selectedVersion = Map.lookup dependency selected
+  guard $ maybe true (not <<< Range.includes range) selectedVersion
+  pure
+    { dependency
+    , package
+    , packageDirectDependants: Array.length (directDependants baseline manifests package)
+    , packageTransitiveDependants: Array.length (transitiveDependants baseline manifests package)
+    , range
+    , selectedVersion
+    , version
+    }
+
+directDependants :: Map PackageName Version -> ManifestIndex -> PackageName -> Array PackageName
+directDependants packages manifests dependency = Array.mapMaybe isDependant (Map.toUnfoldable packages)
+  where
+  isDependant (Tuple name version) = do
+    Manifest manifest <- ManifestIndex.lookup name version manifests
+    name <$ guard (Map.member dependency manifest.dependencies)
+
+transitiveDependants :: Map PackageName Version -> ManifestIndex -> PackageName -> Array PackageName
+transitiveDependants packages manifests dependency = Array.fromFoldable $ Set.delete dependency $ go (Set.singleton dependency) [ dependency ]
+  where
+  go seen [] = seen
+  go seen frontier = do
+    let discovered = Set.fromFoldable (frontier >>= directDependants packages manifests)
+    let next = Set.difference discovered seen
+    go (Set.union seen next) (Array.fromFoldable next)
+
+daysBetween :: DateTime -> DateTime -> Int
+daysBetween from to = do
+  let Days days = DateTime.diff to from
+  max 0 (Int.floor days)
+
+renderMarkdown :: Report -> String
+renderMarkdown report = String.joinWith "\n"
+  [ "# Weekly package set version report"
+  , ""
+  , "Package set: `" <> Version.print report.packageSet <> "` (PureScript `" <> Version.print report.compiler <> "`)"
+  , "Generated: `" <> Internal.Codec.formatIso8601 report.generatedAt <> "`"
+  , "Verification: **" <> report.verification.status <> "**"
+  , maybe "" (\error -> "\nVerification error:\n```text\n" <> String.take 4_000 error <> "\n```") report.verification.error
+  , ""
+  , "## Planned update"
+  , ""
+  , if Map.isEmpty report.plan.packages then "No package updates were planned."
+    else String.joinWith "\n" do
+      Tuple name version <- Map.toUnfoldable report.plan.packages
+      [ "- `" <> PackageName.print name <> "@" <> Version.print version <> "`" ]
+  , if report.plan.searchTruncated then "\n⚠️ Planner search limit reached; this is the best compatible plan found so far and will not be submitted automatically." else ""
+  , maybe "" (\error -> "\nPlanner error: " <> error) report.plan.error
+  , ""
+  , "## Pending versions"
+  , ""
+  , renderPendingPackages report.pending
+  ]
+  where
+  renderPendingPackages pending
+    | Array.null pending = "No package versions are pending."
+    | otherwise = do
+        let visible = Array.take 100 pending
+        let omitted = Array.length pending - Array.length visible
+        String.joinWith "\n\n" (map renderPending visible)
+          <> if omitted > 0 then "\n\n_" <> show omitted <> " more pending packages are available in the JSON artifact._" else ""
+
+  renderPending pending = String.joinWith "\n"
+    [ "### `" <> PackageName.print pending.name <> "` " <> Version.print pending.current <> " → " <> Version.print pending.candidate
+    , ""
+    , "- Stale for **" <> show pending.staleDays <> " days** (since `" <> Internal.Codec.formatIso8601 pending.staleSince <> "`)"
+    , "- Dependants in the current set: **" <> show pending.directDependants <> " direct**, **" <> show pending.transitiveDependants <> " transitive**"
+    , "- Planned version: " <> maybe "none" (\version -> "`" <> Version.print version <> "`") pending.planned
+    , "- Latest candidate compatible with the set compiler: **" <> if pending.candidateCompilerCompatible then "yes**" else "no**"
+    , renderRelations "Held back by" pending.blockers
+    , renderRelations "Candidate blocked by" pending.blockedBy
+    ]
+
+  renderRelations label relations
+    | Array.null relations = "- " <> label <> ": none"
+    | otherwise = "- " <> label <> ":\n" <> String.joinWith "\n" (map (renderRelation >>> ("  - " <> _)) relations)
+
+  renderRelation relation = String.joinWith " "
+    [ "`" <> PackageName.print relation.package <> "@" <> Version.print relation.version <> "` requires"
+    , "`" <> PackageName.print relation.dependency <> " " <> Range.print relation.range <> "`"
+    , "but the proposed version is"
+    , maybe "missing" (\version -> "`" <> Version.print version <> "`") relation.selectedVersion
+    , "(" <> show relation.packageDirectDependants <> " direct, " <> show relation.packageTransitiveDependants <> " transitive dependants)"
+    ]
diff --git a/scripts/test/Main.purs b/scripts/test/Main.purs
index 9bacfbcb..1bf8eba5 100644
--- a/scripts/test/Main.purs
+++ b/scripts/test/Main.purs
@@ -2,15 +2,21 @@ module Test.Registry.Scripts.Main (main) where
 
 import Registry.App.Prelude
 
+import Codec.JSON.DecodeError as CJ.DecodeError
+import Data.Array as Array
 import Data.DateTime (DateTime)
 import Data.Map as Map
+import Data.Set as Set
 import Data.Time.Duration (Hours(..))
+import Registry.ManifestIndex (IncludeRanges(..), ManifestIndex)
+import Registry.ManifestIndex as ManifestIndex
 import Registry.Metadata (Metadata)
 import Registry.Metadata as Metadata
 import Registry.PackageName (PackageName)
 import Registry.PackageSet (PackageSet)
 import Registry.PackageSet as PackageSet
 import Registry.Scripts.PackageSetUpdater as PackageSetUpdater
+import Registry.Scripts.VersionCheck as VersionCheck
 import Registry.Test.Assert as Assert
 import Registry.Test.Utils as Utils
 import Registry.Version (Version)
@@ -61,6 +67,78 @@ main = runSpecAndExitProcess [ consoleReporter ] do
       PackageSetUpdater.selectPackageSetCandidates (PackageSetUpdater.RecentUploads now (Hours 24.0)) packageSet metadata
         `Assert.shouldEqual` expected
 
+  Spec.describe "VersionCheck" do
+    Spec.it "plans coordinated updates, falls back to a compatible intermediate version, and reports blockers" do
+      let fixtures = versionCheckFixtures
+      let generatedAt = Utils.unsafeDateTime "2024-01-10T00:00:00.000Z"
+      let report = VersionCheck.buildReport generatedAt fixtures.packageSet fixtures.metadata fixtures.manifests
+      let
+        expectedPlan = Map.fromFoldable
+          [ Tuple (Utils.unsafePackageName "alpha") (Utils.unsafeVersion "2.0.0")
+          , Tuple (Utils.unsafePackageName "beta") (Utils.unsafeVersion "2.0.0")
+          , Tuple (Utils.unsafePackageName "gamma") (Utils.unsafeVersion "1.5.0")
+          ]
+
+      report.plan.error `Assert.shouldEqual` Nothing
+      report.plan.packages `Assert.shouldEqual` expectedPlan
+      report.plan.searchTruncated `Assert.shouldEqual` false
+
+      let gamma = Utils.fromJust "Missing gamma report." $ Array.find (_.name >>> eq (Utils.unsafePackageName "gamma")) report.pending
+      gamma.candidate `Assert.shouldEqual` Utils.unsafeVersion "2.0.0"
+      gamma.planned `Assert.shouldEqual` Just (Utils.unsafeVersion "1.5.0")
+      gamma.staleSince `Assert.shouldEqual` Utils.unsafeDateTime "2023-12-01T00:00:00.000Z"
+      gamma.staleDays `Assert.shouldEqual` 40
+      gamma.directDependants `Assert.shouldEqual` 2
+      gamma.transitiveDependants `Assert.shouldEqual` 3
+      map _.package gamma.blockers `Assert.shouldEqual` [ Utils.unsafePackageName "consumer", Utils.unsafePackageName "delta" ]
+      gamma.blockedBy `Assert.shouldEqual` []
+
+      let consumer = Utils.fromJust "Missing consumer report." $ Array.find (_.name >>> eq (Utils.unsafePackageName "consumer")) report.pending
+      map _.dependency consumer.blockedBy `Assert.shouldEqual` [ Utils.unsafePackageName "gamma" ]
+
+      case parseJson VersionCheck.reportCodec (printJson VersionCheck.reportCodec report) of
+        Left error -> Assert.fail $ CJ.DecodeError.print error
+        Right decoded -> decoded `Assert.shouldEqual` report
+
+    Spec.it "uses the latest version when equally-sized plans are available" do
+      let fixtures = versionCheckFixtures
+      let planned = VersionCheck.planPackageSet fixtures.packageSet fixtures.metadata fixtures.manifests
+      planned `Assert.shouldEqual` Right
+        { packages: Map.fromFoldable
+            [ Tuple (Utils.unsafePackageName "alpha") (Utils.unsafeVersion "2.0.0")
+            , Tuple (Utils.unsafePackageName "beta") (Utils.unsafeVersion "2.0.0")
+            , Tuple (Utils.unsafePackageName "gamma") (Utils.unsafeVersion "1.5.0")
+            ]
+        , searchTruncated: false
+        }
+
+    Spec.it "preserves existing range drift without allowing an update to introduce it" do
+      let
+        packageSet = mkPackageSet $ Map.fromFoldable
+          [ Tuple (Utils.unsafePackageName "dependency") (Utils.unsafeVersion "1.0.0")
+          , Tuple (Utils.unsafePackageName "independent") (Utils.unsafeVersion "1.0.0")
+          , Tuple (Utils.unsafePackageName "legacy") (Utils.unsafeVersion "1.0.0")
+          ]
+        metadata = Map.fromFoldable
+          [ Utils.unsafeMetadata "dependency" [ Tuple "1.0.0" [ "0.15.10" ], Tuple "3.0.0" [ "0.15.10" ] ]
+          , Utils.unsafeMetadata "independent" [ Tuple "1.0.0" [ "0.15.10" ], Tuple "2.0.0" [ "0.15.10" ] ]
+          , Utils.unsafeMetadata "legacy" [ Tuple "1.0.0" [ "0.15.10" ] ]
+          ]
+        manifestSet = Set.fromFoldable
+          [ Utils.unsafeManifest "dependency" "1.0.0" []
+          , Utils.unsafeManifest "dependency" "3.0.0" []
+          , Utils.unsafeManifest "independent" "1.0.0" []
+          , Utils.unsafeManifest "independent" "2.0.0" []
+          , Utils.unsafeManifest "legacy" "1.0.0" [ Tuple "dependency" ">=2.0.0 <3.0.0" ]
+          ]
+        manifests = Utils.fromRight "Could not build range-drift manifest index." $ ManifestIndex.fromSet IgnoreRanges manifestSet
+
+      VersionCheck.planPackageSet packageSet metadata manifests
+        `Assert.shouldEqual` Right
+          { packages: Map.singleton (Utils.unsafePackageName "independent") (Utils.unsafeVersion "2.0.0")
+          , searchTruncated: false
+          }
+
 mkPackageSet :: Map PackageName Version -> PackageSet
 mkPackageSet packages = PackageSet.PackageSet
   { version: Utils.unsafeVersion "1.0.0"
@@ -73,3 +151,53 @@ withPublishedTime :: forall a. DateTime -> Tuple a Metadata -> Tuple a Metadata
 withPublishedTime publishedTime (Tuple name (Metadata.Metadata metadata)) =
   Tuple name $ Metadata.Metadata $ metadata
     { published = map (_ { publishedTime = publishedTime }) metadata.published }
+
+type VersionCheckFixtures =
+  { manifests :: ManifestIndex
+  , metadata :: Map PackageName Metadata
+  , packageSet :: PackageSet
+  }
+
+versionCheckFixtures :: VersionCheckFixtures
+versionCheckFixtures = do
+  let
+    packageSet = mkPackageSet $ Map.fromFoldable
+      [ Tuple (Utils.unsafePackageName "alpha") (Utils.unsafeVersion "1.0.0")
+      , Tuple (Utils.unsafePackageName "beta") (Utils.unsafeVersion "1.0.0")
+      , Tuple (Utils.unsafePackageName "consumer") (Utils.unsafeVersion "1.0.0")
+      , Tuple (Utils.unsafePackageName "delta") (Utils.unsafeVersion "1.0.0")
+      , Tuple (Utils.unsafePackageName "epsilon") (Utils.unsafeVersion "1.0.0")
+      , Tuple (Utils.unsafePackageName "gamma") (Utils.unsafeVersion "1.0.0")
+      ]
+    metadata = Map.fromFoldable
+      [ Utils.unsafeMetadata "alpha" [ Tuple "1.0.0" [ "0.15.10" ], Tuple "2.0.0" [ "0.15.10" ] ]
+      , Utils.unsafeMetadata "beta" [ Tuple "1.0.0" [ "0.15.10" ], Tuple "2.0.0" [ "0.15.10" ] ]
+      , Utils.unsafeMetadata "consumer" [ Tuple "1.0.0" [ "0.15.10" ], Tuple "2.0.0" [ "0.15.10" ] ]
+      , Utils.unsafeMetadata "delta" [ Tuple "1.0.0" [ "0.15.10" ] ]
+      , Utils.unsafeMetadata "epsilon" [ Tuple "1.0.0" [ "0.15.10" ] ]
+      , Utils.unsafeMetadata "gamma" [ Tuple "1.0.0" [ "0.15.10" ], Tuple "1.5.0" [ "0.15.10" ], Tuple "2.0.0" [ "0.15.10" ] ]
+          # withVersionPublishedTime "1.5.0" "2023-12-01T00:00:00.000Z"
+          # withVersionPublishedTime "2.0.0" "2024-01-05T00:00:00.000Z"
+      ]
+    manifestSet = Set.fromFoldable
+      [ Utils.unsafeManifest "alpha" "1.0.0" [ Tuple "beta" ">=1.0.0 <2.0.0" ]
+      , Utils.unsafeManifest "alpha" "2.0.0" [ Tuple "beta" ">=2.0.0 <3.0.0" ]
+      , Utils.unsafeManifest "beta" "1.0.0" []
+      , Utils.unsafeManifest "beta" "2.0.0" []
+      , Utils.unsafeManifest "consumer" "1.0.0" [ Tuple "gamma" ">=1.0.0 <2.0.0" ]
+      , Utils.unsafeManifest "consumer" "2.0.0" [ Tuple "gamma" ">=2.0.0 <3.0.0" ]
+      , Utils.unsafeManifest "delta" "1.0.0" [ Tuple "gamma" ">=1.0.0 <2.0.0" ]
+      , Utils.unsafeManifest "epsilon" "1.0.0" [ Tuple "delta" ">=1.0.0 <2.0.0" ]
+      , Utils.unsafeManifest "gamma" "1.0.0" []
+      , Utils.unsafeManifest "gamma" "1.5.0" []
+      , Utils.unsafeManifest "gamma" "2.0.0" []
+      ]
+    manifests = Utils.fromRight "Could not build version-check manifest index." $ ManifestIndex.fromSet IgnoreRanges manifestSet
+  { manifests, metadata, packageSet }
+
+withVersionPublishedTime :: forall a. String -> String -> Tuple a Metadata -> Tuple a Metadata
+withVersionPublishedTime version publishedTime (Tuple name (Metadata.Metadata metadata)) = do
+  let parsedVersion = Utils.unsafeVersion version
+  let parsedTime = Utils.unsafeDateTime publishedTime
+  Tuple name $ Metadata.Metadata $ metadata
+    { published = Map.update (Just <<< (_ { publishedTime = parsedTime })) parsedVersion metadata.published }

From 4800690d3893b62fb6739b16f5616b668658e69c Mon Sep 17 00:00:00 2001
From: Thomas Honeyman <hello@thomashoneyman.com>
Date: Tue, 28 Jul 2026 00:11:31 +0000
Subject: [PATCH 6/8] Automate compile-guided package set updates

---
 .github/workflows/version-check.yml | 226 ++++++++-
 SPEC.md                             |  37 +-
 app-e2e/src/Test/E2E/Scripts.purs   |  30 +-
 app/src/App/API.purs                |  32 +-
 app/src/App/GitHubIssue.purs        |  15 +-
 app/src/App/Server/Router.purs      |   3 +-
 app/test/App/API.purs               | 147 +++++-
 lib/src/Operation.purs              |  54 ++-
 lib/test/Registry/Operation.purs    |  18 +
 scripts/spago.yaml                  |   1 +
 scripts/src/PackageSetPlanner.purs  | 706 ++++++++++++++++++++++++++++
 scripts/src/PackageSetUpdater.purs  | 217 +++++++--
 scripts/src/VersionCheck.purs       | 533 ++++++++++-----------
 scripts/test/Main.purs              | 411 +++++++++++-----
 spago.lock                          |   1 +
 15 files changed, 1886 insertions(+), 545 deletions(-)
 create mode 100644 scripts/src/PackageSetPlanner.purs

diff --git a/.github/workflows/version-check.yml b/.github/workflows/version-check.yml
index e1a9b5f1..6d54692b 100644
--- a/.github/workflows/version-check.yml
+++ b/.github/workflows/version-check.yml
@@ -1,8 +1,8 @@
-name: Weekly package set version check
+name: Daily package set planning
 
 on:
   schedule:
-    - cron: '0 6 * * 1'
+    - cron: '0 6 * * *'
   workflow_dispatch:
 
 permissions:
@@ -10,13 +10,16 @@ permissions:
   issues: write
 
 concurrency:
-  group: weekly-package-set-version-check
+  group: package-set-version-check
   cancel-in-progress: false
 
 jobs:
   version-check:
     runs-on: ubuntu-latest
-    timeout-minutes: 90
+    # Planning performs at most 96 incremental compile probes, then a submitted
+    # server job is polled for at most 60 minutes. Leave enough headroom that a
+    # difficult plan can still emit its report and reconcile trustee issues.
+    timeout-minutes: 180
 
     steps:
       - name: Checkout code
@@ -30,33 +33,206 @@ jobs:
         with:
           use-flakehub: false
 
-      - name: Plan and verify pending package set updates
-        run: nix run .#version-check -- --verify --output version-check.json --markdown version-check.md
+      - name: Plan, verify, and submit pending package set updates
+        run: nix run .#version-check -- --verify --submit --output version-check.json --markdown version-check.md
 
       - name: Upload report
+        if: ${{ !cancelled() }}
         uses: actions/upload-artifact@v4
         with:
           name: package-set-version-check
           path: |
             version-check.json
             version-check.md
+          if-no-files-found: warn
+          retention-days: 14
 
-      - name: Update rolling report issue
-        env:
-          GH_TOKEN: ${{ github.token }}
-          REPOSITORY: ${{ github.repository }}
-        run: |
-          set -euo pipefail
-
-          title='Weekly package set version report'
-          issue_number=$(
-            gh issue list --repo "$REPOSITORY" --state open --search "$title in:title" --limit 100 --json number,title \
-              | jq -r --arg title "$title" '.[] | select(.title == $title) | .number' \
-              | sed -n '1p'
-          )
-
-          if [[ -n "$issue_number" ]]; then
-            gh issue edit "$issue_number" --repo "$REPOSITORY" --body-file version-check.md
-          else
-            gh issue create --repo "$REPOSITORY" --title "$title" --body-file version-check.md
-          fi
+      - name: Reconcile rolling report and trustee decisions
+        if: ${{ !cancelled() }}
+        uses: actions/github-script@v8
+        with:
+          github-token: ${{ github.token }}
+          script: |
+            const fs = require("node:fs");
+
+            const expectedRepository = "purescript/registry-dev";
+            const repository = `${context.repo.owner}/${context.repo.repo}`;
+            if (repository !== expectedRepository) {
+              throw new Error(`Refusing to manage issues in ${repository}; expected ${expectedRepository}.`);
+            }
+
+            const summaryMarker = "<!-- registry-version-check:summary:v1 -->";
+            const decisionMarker = "<!-- registry-version-check:decision:v1 -->";
+            const componentMarkerPrefix = "<!-- registry-version-check:component:";
+            const fingerprintMarkerPrefix = "<!-- registry-version-check:fingerprint:";
+            const markerSuffix = " -->";
+            const summaryTitle = "Package set planning report";
+
+            const fail = message => { throw new Error(message); };
+            const isObject = value => value !== null && typeof value === "object" && !Array.isArray(value);
+            const normalize = value => (value || "").replace(/\r\n/g, "\n");
+            const lines = value => normalize(value).split("\n");
+            const hasExactMarker = (issue, marker) => lines(issue.body).includes(marker);
+            const markerFor = (prefix, value) => `${prefix}${value}${markerSuffix}`;
+            const hasReservedMarker = value => lines(value).some(line => line.startsWith("<!-- registry-version-check:"));
+
+            let report;
+            try {
+              report = JSON.parse(fs.readFileSync("version-check.json", "utf8"));
+            } catch (error) {
+              fail(`Could not read the structured version-check report: ${error.message}`);
+            }
+            const markdown = normalize(fs.readFileSync("version-check.md", "utf8")).trimEnd();
+            if (!isObject(report)) fail("The version-check report must be a JSON object.");
+            if (typeof report.manualInterventionsDeferred !== "boolean") fail("The version-check report is missing manualInterventionsDeferred.");
+            if (!isObject(report.manualAnalysis) || typeof report.manualAnalysis.searchTruncated !== "boolean") {
+              fail("The version-check report is missing manualAnalysis state.");
+            }
+            if (markdown.length === 0) fail("The generated Markdown report is empty.");
+            if (hasReservedMarker(markdown)) fail("The generated Markdown contains a reserved automation marker.");
+            const summaryBody = `${summaryMarker}\n\n${markdown}\n`;
+            if (summaryBody.length > 65536) fail("The rolling report issue body is larger than 65536 characters.");
+
+            const allItems = await github.paginate(github.rest.issues.listForRepo, {
+              owner: context.repo.owner, repo: context.repo.repo, state: "all", per_page: 100,
+            });
+            const allIssues = allItems.filter(item => !item.pull_request);
+            const summaryIssues = allIssues.filter(issue => hasExactMarker(issue, summaryMarker));
+            if (summaryIssues.length > 1) fail(`Found ${summaryIssues.length} rolling issues with the exact summary marker.`);
+            if (summaryIssues.some(issue => lines(issue.body).filter(line => line === summaryMarker).length !== 1)) {
+              fail("The rolling issue has duplicate summary markers.");
+            }
+            if (summaryIssues.some(issue => hasExactMarker(issue, decisionMarker))) fail("An issue contains both summary and decision markers.");
+
+            const summary = summaryIssues[0];
+            if (!summary) {
+              await github.rest.issues.create({ owner: context.repo.owner, repo: context.repo.repo, title: summaryTitle, body: summaryBody });
+            } else if (summary.state !== "open" || summary.title !== summaryTitle || normalize(summary.body) !== summaryBody) {
+              await github.rest.issues.update({
+                owner: context.repo.owner, repo: context.repo.repo, issue_number: summary.number,
+                title: summaryTitle, body: summaryBody, state: "open",
+              });
+            }
+
+            if (
+              !isObject(report.plan)
+              || (report.plan.error !== null && typeof report.plan.error !== "string")
+              || !isObject(report.plan.packages)
+              || typeof report.plan.searchTruncated !== "boolean"
+            ) {
+              fail("The version-check report contains invalid automatic planning state.");
+            }
+            const verificationStatuses = ["verified", "not-needed", "incomplete", "failed", "infrastructure-failed"];
+            if (!isObject(report.verification)
+              || (report.verification.error !== null && typeof report.verification.error !== "string")
+              || !verificationStatuses.includes(report.verification.status)) {
+              fail("The version-check report contains invalid automatic verification state.");
+            }
+            if (report.verification.status === "infrastructure-failed") {
+              core.warning("Skipping trustee decision reconciliation because automatic verification hit an infrastructure failure.");
+              return;
+            }
+            if (report.manualAnalysis.error !== null || report.manualAnalysis.searchTruncated === true) {
+              core.warning("Skipping trustee decision reconciliation because manual-intervention analysis failed or was truncated.");
+              return;
+            }
+            if (report.manualInterventionsDeferred === true) {
+              core.warning("Skipping trustee decision reconciliation until residual decisions are recomputed against the newly published baseline.");
+              return;
+            }
+            if (!Array.isArray(report.manualInterventions)) fail("The version-check report is missing the manualInterventions array.");
+
+            const componentPattern = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,127}$/;
+            const fingerprintPattern = /^[A-Za-z0-9][A-Za-z0-9._:/+=-]{0,199}$/;
+            const interventions = report.manualInterventions.map((intervention, index) => {
+              const location = `manualInterventions[${index}]`;
+              if (!isObject(intervention)) fail(`${location} must be an object.`);
+              const { component, fingerprint, title, markdownBody, removal } = intervention;
+              if (typeof component !== "string" || !componentPattern.test(component)) fail(`${location}.component is not a safe stable component identifier.`);
+              if (typeof fingerprint !== "string" || !fingerprintPattern.test(fingerprint)) fail(`${location}.fingerprint is not a safe non-empty fingerprint.`);
+              if (typeof title !== "string" || title.trim() !== title || title.length === 0 || title.length > 256 || /[\r\n]/.test(title)) {
+                fail(`${location}.title must be a non-empty single-line GitHub issue title.`);
+              }
+              if (typeof markdownBody !== "string" || markdownBody.trim().length === 0 || hasReservedMarker(markdownBody)) {
+                fail(`${location}.markdownBody must be non-empty Markdown without reserved markers.`);
+              }
+              if (!isObject(removal) || typeof removal.verified !== "boolean" || !isObject(removal.payload)) {
+                fail(`${location}.removal must contain a Boolean verified field and an object payload.`);
+              }
+              const payloadKeys = Object.keys(removal.payload);
+              if (payloadKeys.some(key => !["expectedBaseline", "compiler", "packages"].includes(key))) {
+                fail(`${location}.removal.payload contains an unexpected field.`);
+              }
+              if (typeof removal.payload.expectedBaseline !== "string" || removal.payload.expectedBaseline.length === 0) {
+                fail(`${location}.removal.payload.expectedBaseline must be a non-empty string.`);
+              }
+              if ("compiler" in removal.payload && typeof removal.payload.compiler !== "string") {
+                fail(`${location}.removal.payload.compiler must be a string when present.`);
+              }
+              if (!isObject(removal.payload.packages)) {
+                fail(`${location}.removal.payload.packages must be an object.`);
+              }
+              if (Object.values(removal.payload.packages).some(value => value !== null && typeof value !== "string")) {
+                fail(`${location}.removal.payload.packages values must be strings or null removals.`);
+              }
+              if (removal.verified && !Object.values(removal.payload.packages).some(value => value === null)) {
+                fail(`${location}.removal.payload.packages must contain a removal when verified is true.`);
+              }
+              const payloadHeading = removal.verified ? "## Compile-verified removal payload" : "## Diagnostic payload (not compile-verified)";
+              const payloadNote = removal.verified
+                ? "The planner atomically verified this package-set payload. A trustee must review it before taking action."
+                : "The planner did not find a compile-verified removal for this component. This payload is diagnostic only and must not be applied as a verified plan.";
+              const body = [
+                decisionMarker, markerFor(componentMarkerPrefix, component), markerFor(fingerprintMarkerPrefix, fingerprint), "",
+                normalize(markdownBody).trimEnd(), "", payloadHeading, "", payloadNote, "",
+                "```json", JSON.stringify(removal.payload, null, 2), "```",
+              ].join("\n");
+              if (body.length > 65536) fail(`${location} produces a GitHub issue body larger than 65536 characters.`);
+              return { body, component, fingerprint, title };
+            });
+
+            const components = interventions.map(intervention => intervention.component);
+            const fingerprints = interventions.map(intervention => intervention.fingerprint);
+            if (new Set(components).size !== components.length) fail("manualInterventions contains duplicate component identifiers.");
+            if (new Set(fingerprints).size !== fingerprints.length) fail("manualInterventions contains duplicate fingerprints.");
+
+            const decisionIssues = allIssues.filter(issue => hasExactMarker(issue, decisionMarker));
+            if (decisionIssues.some(issue => hasExactMarker(issue, summaryMarker))) fail("An issue contains both summary and decision markers.");
+            const existingByComponent = new Map();
+            const existingByFingerprint = new Map();
+            for (const issue of decisionIssues) {
+              const issueLines = lines(issue.body);
+              if (issueLines.filter(line => line === decisionMarker).length !== 1) fail(`Decision issue #${issue.number} has duplicate decision markers.`);
+              const componentMarkers = issueLines.filter(line => line.startsWith(componentMarkerPrefix) && line.endsWith(markerSuffix));
+              const fingerprintMarkers = issueLines.filter(line => line.startsWith(fingerprintMarkerPrefix) && line.endsWith(markerSuffix));
+              if (componentMarkers.length !== 1 || fingerprintMarkers.length !== 1) fail(`Decision issue #${issue.number} has malformed identity markers.`);
+              const component = componentMarkers[0].slice(componentMarkerPrefix.length, -markerSuffix.length);
+              const fingerprint = fingerprintMarkers[0].slice(fingerprintMarkerPrefix.length, -markerSuffix.length);
+              if (!componentPattern.test(component) || !fingerprintPattern.test(fingerprint)
+                || componentMarkers[0] !== markerFor(componentMarkerPrefix, component)
+                || fingerprintMarkers[0] !== markerFor(fingerprintMarkerPrefix, fingerprint)) {
+                fail(`Decision issue #${issue.number} has invalid identity markers.`);
+              }
+              if (existingByComponent.has(component)) fail(`Multiple decision issues have the exact component marker for ${component}.`);
+              if (existingByFingerprint.has(fingerprint)) fail(`Multiple decision issues have the exact fingerprint marker ${fingerprint}.`);
+              existingByComponent.set(component, issue);
+              existingByFingerprint.set(fingerprint, issue);
+            }
+            for (const intervention of interventions) {
+              const fingerprintOwner = existingByFingerprint.get(intervention.fingerprint);
+              if (fingerprintOwner && fingerprintOwner !== existingByComponent.get(intervention.component)) {
+                fail(`Fingerprint ${intervention.fingerprint} belongs to decision issue #${fingerprintOwner.number} for another component.`);
+              }
+            }
+
+            for (const intervention of interventions) {
+              const existing = existingByComponent.get(intervention.component);
+              if (!existing) {
+                await github.rest.issues.create({ owner: context.repo.owner, repo: context.repo.repo, title: intervention.title, body: intervention.body });
+              } else if (existing.state !== "open" || existing.title !== intervention.title || normalize(existing.body) !== intervention.body) {
+                await github.rest.issues.update({
+                  owner: context.repo.owner, repo: context.repo.repo, issue_number: existing.number,
+                  title: intervention.title, body: intervention.body, state: "open",
+                });
+              }
+            }
diff --git a/SPEC.md b/SPEC.md
index 77883eac..be322b51 100644
--- a/SPEC.md
+++ b/SPEC.md
@@ -779,12 +779,13 @@ Anyone can suggest a package set update to the registry. However, community memb
 
 A package set update must be submitted to the registry via GitHub issues on the registry repository. The body of the issue should contain the JSON object specified below, optionally within a code fence.
 
-A package set update is an object with two keys: `compiler`, an optional field that, if set, will update the compiler version used to compile the package sets (it cannot be downgraded), and `packages`, an object where keys are package names and values are either a version number or `null`. A version number indicates the package should be added to the set or updated to the given version, and `null` indicates the package should be dropped from the package set.
+A package set update is an object with three keys: `expectedBaseline`, an optional package set version that the update was planned and verified against; `compiler`, an optional field that, if set, will update the compiler version used to compile the package sets (it cannot be downgraded); and `packages`, an object where keys are package names and values are either a version number or `null`. A version number indicates the package should be added to the set or updated to the given version, and `null` indicates the package should be dropped from the package set. If `expectedBaseline` is present and is not the latest package set version when the operation executes, then the operation is rejected before validation, compilation, or publication. The field may be omitted for compatibility with manually submitted updates, which apply to the latest package set available when they execute.
 
 ```jsonc
 { // Sets the package set compiler version to 0.15.2
+  "expectedBaseline": "2.1.1",
   "compiler": "0.15.2",
-  "packages" {
+  "packages": {
     // Updates the `aff` package to v8.0.0
     "aff": "8.0.0",
     // Removes the `argonaut` package from the package sets altogether
@@ -812,13 +813,15 @@ The suggested new package set can only be released if:
 1. All packages in the set depend only on other packages in the set
 2. All packages in the set can be compiled together
 
+Package set self-containment concerns dependency names, not the version ranges in package manifests. Every dependency name must occur in the package set, but its manifest range need not include the exact version selected by the set. Compiling the exact package versions in the set with the set's exact compiler version is the authoritative validity check.
+
 To verify the package set, we take the following steps:
 
-1. We apply the suggested changes to the package set and verify that the package set is still self-contained. If not, the update is rejected.
+1. We apply all suggested changes to the package set as one exact batch and verify that the package set is still self-contained. If not, the update is rejected.
 2. We install the previous package set and compile it. This ensures we are beginning from a known good state.
 3. We install the new package set (uninstalling any packages that are removed) and compile the package set again. If compilation fails then the update is rejected.
 
-When we have verified the package set is self-contained and all packages compile together then we can release the package set.
+When we have verified the package set is self-contained and all packages compile together then we can release the package set. A submitted package set update is atomic: either its entire exact payload is released or it fails without releasing a subset.
 
 ##### Releasing the Package Set
 
@@ -874,27 +877,25 @@ If documentation publishing fails (for example, due to a transient network error
 
 #### 6.3 Publish to Package Sets
 
-The registry attempts to produce a new package set automatically every day, so long as packages have been uploaded that could be added or updated. No packages are ever dropped from a package set automatically; the only time packages are dropped from the package sets are during manual releases.
+The registry attempts to produce a new package set automatically every day when eligible package versions exist. The latest package set and its compiler version are the starting point for every automatic plan.
 
-Every day, the registry executes the following steps:
+Newer registry versions of packages already in the package set remain candidates until they are included or superseded by the package set itself. They do not cease to be candidates merely because an automatic run could not include them or because time has passed since publication. An automatic plan may coordinate upgrades to several packages and may select an intermediate newer version instead of only the latest release when that produces a valid set.
 
-First, we read the contents of the latest package set release and gather all package versions that have been uploaded to the registry since that release. These package versions are the "batch" of packages that we are considering for automatic inclusion to the next package set.
+Packages that have never appeared in a package set are eligible only while they are recent additions. Their candidate set is recursively expanded with any dependency names absent from the current package set so the planner can consider a self-contained addition.
 
-Second, we filter out any packages where, based on their metadata and manifest files alone, we know they can't be added to the package set. This happens for one of three reasons:
+Every automatic plan must satisfy these constraints:
 
-1. They have a dependency that is neither in the package sets nor in the batch that is up for consideration
-2. They have had multiple releases since the last package set, in which case we only take the highest version
-3. They already have a higher version published in a previous package set
+1. It does not remove a package.
+2. It does not downgrade a package.
+3. It does not change the compiler version.
+4. Every dependency name in the resulting set occurs in that set. Manifest version ranges are ignored for this self-containment check.
+5. The exact resulting package set compiles as a whole with the unchanged, exact compiler version.
 
-Third, we attempt to add the rest of the batch of package versions to the package set. Processing the batch follows these steps:
+The whole-set compiler result is authoritative: manifest version ranges do not prevent an exact selection from being a valid package set, and manifest compatibility alone does not prove that a selection is valid. Each selected plan is submitted and released as one exact atomic package set update according to [Section 5.5 (Update the Package Set)](#55-update-the-package-set).
 
-1. We install the previous package set and compile it.
-2. We attempt to upgrade all package versions from the batch at once in the package set. Once the new versions are installed, we compile the package set. If it succeeds, then we're done.
-3. If we couldn't compile the whole batch, then we order the batch first by their dependencies and then by their upload time. Packages with no dependencies on other packages in the batch go first, and ties are broken by upload time: older uploads go first. Then, we attempt to add packages to the package set one-by-one.
-4. If a package fails to compile with the rest of the package set, then it is filtered from the batch.
-5. Once there are no more packages to consider in the batch, the new package set is ready.
+If an otherwise desirable upgrade requires removing packages, it is not an automatic plan. Registry Trustees handle such cases using the manual intervention process in [Section 9.5 (Package Sets)](#manual-intervention-in-the-package-sets-via-the-package-sets-api).
 
-Fourth, we release the new package set (if we could produce one). Automatic package sets follow the versioning policy described in [Section 5.5 (Update the Package Set)](#releasing-the-package-set).
+The automation reports residual upgrades it could not apply, including compiler evidence. It may report an exact removal-containing payload as compile-verified only after compiling that full payload against its original package set baseline. Such payloads are advisory and are never submitted automatically; a Registry Trustee must decide whether to apply them. Infrastructure failures and bounded searches must be reported distinctly from package incompatibility.
 
 ## 7. Non-JavaScript Backends
 
diff --git a/app-e2e/src/Test/E2E/Scripts.purs b/app-e2e/src/Test/E2E/Scripts.purs
index 424eec9a..bd6e0420 100644
--- a/app-e2e/src/Test/E2E/Scripts.purs
+++ b/app-e2e/src/Test/E2E/Scripts.purs
@@ -20,7 +20,10 @@ import Registry.App.Effect.Cache as Cache
 import Registry.App.Effect.Env as Env
 import Registry.App.Effect.GitHub as GitHub
 import Registry.App.Effect.Log as Log
+import Registry.App.Effect.PackageSets as PackageSets
 import Registry.App.Effect.Registry as Registry
+import Registry.App.Effect.Storage as Storage
+import Registry.Foreign.FSExtra as FS.Extra
 import Registry.Foreign.Octokit as Octokit
 import Registry.Location (Location(..))
 import Registry.Operation (AuthenticatedPackageOperation(..))
@@ -140,19 +143,20 @@ spec = do
       jobs <- Client.getJobs
       let packageSetJobs = Array.filter isPackageSetJob jobs
       case Array.head packageSetJobs of
-        Just (PackageSetJob { payload }) ->
-          case payload of
-            Operation.PackageSetUpdate { packages } ->
-              case Map.lookup typeEqualityName packages of
-                Just (Just _) -> pure unit
-                _ -> Assert.fail "Expected type-equality in package set update"
+        Just (PackageSetJob { payload }) -> do
+          let { packages } = Operation.packageSetUpdateData payload
+          case Map.lookup typeEqualityName packages of
+            Just (Just _) -> pure unit
+            _ -> Assert.fail "Expected type-equality in package set update"
         Just _ -> Assert.fail "Expected PackageSetJob but got different job type"
         Nothing -> Assert.fail "Expected package set job to be enqueued"
 
 -- | Common environment for running read-only registry scripts in E2E tests
 type RegistryScriptSetup =
-  { resourceEnv :: Env.ResourceEnv
+  { cache :: FilePath
+  , resourceEnv :: Env.ResourceEnv
   , registryEnv :: Registry.RegistryEnv
+  , workdir :: FilePath
   }
 
 type GitHubScriptSetup =
@@ -171,6 +175,9 @@ setupRegistryScript = do
   resourceEnv <- liftEffect Env.lookupResourceEnv
   registryCacheRef <- liftAff Cache.newCacheRef
   debouncer <- liftAff Registry.newDebouncer
+  let workdir = Path.concat [ stateDir, "scratch" ]
+  let cache = Path.concat [ workdir, ".cache" ]
+  liftAff $ FS.Extra.ensureDirectory cache
   let
     registryEnv :: Registry.RegistryEnv
     registryEnv =
@@ -178,11 +185,11 @@ setupRegistryScript = do
       , pull: Git.Autostash
       , write: Registry.ReadOnly
       , repos: Registry.defaultRepos
-      , workdir: Path.concat [ stateDir, "scratch" ]
+      , workdir
       , debouncer
       , cacheRef: registryCacheRef
       }
-  pure { resourceEnv, registryEnv }
+  pure { cache, resourceEnv, registryEnv, workdir }
 
 setupGitHubScript :: E2E GitHubScriptSetup
 setupGitHubScript = do
@@ -229,12 +236,15 @@ runPackageTransferrerScript = do
 -- | Run the PackageSetUpdater script in Submit mode
 runPackageSetUpdaterScript :: E2E Unit
 runPackageSetUpdaterScript = do
-  { resourceEnv, registryEnv } <- setupRegistryScript
+  { cache, resourceEnv, registryEnv, workdir } <- setupRegistryScript
   result <- liftAff
     $ PackageSetUpdater.runPackageSetUpdater PackageSetUpdater.Submit resourceEnv.registryApiUrl
+    # PackageSets.interpret (PackageSets.handle { workdir })
     # Except.runExcept
     # Registry.interpretRead (Registry.handleRead registryEnv)
+    # Storage.interpret (Storage.handleReadOnly cache)
     # Log.interpret (Log.handleTerminal Quiet)
+    # Env.runResourceEnv resourceEnv
     # Run.runBaseAff'
   case result of
     Left err -> liftAff $ Aff.throwError $ Aff.error $ "PackageSetUpdater failed: " <> err
diff --git a/app/src/App/API.purs b/app/src/App/API.purs
index a4b69c5d..33dd3af5 100644
--- a/app/src/App/API.purs
+++ b/app/src/App/API.purs
@@ -151,9 +151,10 @@ type PackageSetUpdateEffects r = (REGISTRY + PACKAGE_SETS + LOG + EXCEPT String
 -- | been verified at the API boundary, so we don't need to check team membership.
 packageSetUpdate :: forall r. PackageSetJobData -> Run (PackageSetUpdateEffects + r) Unit
 packageSetUpdate details = do
-  let Operation.PackageSetUpdate payload = details.payload
+  let payload = Operation.packageSetUpdateData details.payload
+  let expectedBaseline = Operation.packageSetUpdateExpectedBaseline details.payload
 
-  Log.debug $ "Package set update job starting with payload:\n" <> stringifyJson Operation.packageSetUpdateCodec payload
+  Log.debug $ "Package set update job starting with payload:\n" <> stringifyJson Operation.packageSetOperationCodec details.payload
 
   latestPackageSet <- Registry.readLatestPackageSet >>= case _ of
     Nothing -> do
@@ -162,9 +163,17 @@ packageSetUpdate details = do
     Just set -> pure set
 
   Log.debug $ "Most recent package set was " <> stringifyJson PackageSet.codec latestPackageSet
+  let latestVersion = (un PackageSet latestPackageSet).version
   let prevCompiler = (un PackageSet latestPackageSet).compiler
   let prevPackages = (un PackageSet latestPackageSet).packages
 
+  for_ expectedBaseline \expected -> when (expected /= latestVersion) do
+    Except.throw $ Array.fold
+      [ "Package set update expected baseline " <> Version.print expected
+      , ", but the latest package set is " <> Version.print latestVersion
+      , ". Refusing to apply the update to a different baseline."
+      ]
+
   -- Note: authentication for restricted operations (compiler change, package removal)
   -- is handled at the API boundary in the Router, not here.
 
@@ -225,18 +234,13 @@ packageSetUpdate details = do
 
   let changeSet = candidates.accepted <#> maybe Remove Update
   Log.notice "Attempting to build package set update."
-  PackageSets.upgradeSequential latestPackageSet (fromMaybe prevCompiler payload.compiler) changeSet >>= case _ of
-    Nothing ->
-      Except.throw "No packages could be added to the package set. All packages failed to compile."
-    Just { failed, succeeded, result: packageSet } -> do
-      unless (Map.isEmpty failed) do
-        let
-          formatFailed = String.joinWith "\n" $ Array.catMaybes $ flip map (Map.toUnfoldable failed) \(Tuple name change) ->
-            case change of
-              PackageSets.Update version -> Just $ "  - " <> formatPackageVersion name version
-              PackageSets.Remove -> Nothing
-        Log.warn $ "Some packages could not be added to the set:\n" <> formatFailed
-      let commitMessage = PackageSets.commitMessage latestPackageSet succeeded (un PackageSet packageSet).version
+  -- A submitted payload is exact. Sequential probing is useful for planning,
+  -- but must not turn this operation into a partial release.
+  PackageSets.upgradeAtomic latestPackageSet (fromMaybe prevCompiler payload.compiler) changeSet >>= case _ of
+    Left error ->
+      Except.throw $ "Package set update failed to compile atomically. No changes were published.\n\n" <> error
+    Right packageSet -> do
+      let commitMessage = PackageSets.commitMessage latestPackageSet changeSet (un PackageSet packageSet).version
       Registry.writePackageSet packageSet commitMessage
       Log.notice "Built and released a new package set! Now mirroring to the package-sets repo..."
       Registry.mirrorPackageSet packageSet
diff --git a/app/src/App/GitHubIssue.purs b/app/src/App/GitHubIssue.purs
index 65fdbdd3..dbb2ee8e 100644
--- a/app/src/App/GitHubIssue.purs
+++ b/app/src/App/GitHubIssue.purs
@@ -41,7 +41,7 @@ import Registry.Foreign.JsonRepair as JsonRepair
 import Registry.Foreign.Octokit (GitHubToken, IssueNumber(..), Octokit)
 import Registry.Foreign.Octokit as Octokit
 import Registry.Internal.Format as Internal.Format
-import Registry.Operation (AuthenticatedData, AuthenticatedPackageOperation(..), PackageOperation(..), PackageSetOperation(..))
+import Registry.Operation (AuthenticatedData, AuthenticatedPackageOperation(..), PackageOperation(..), PackageSetOperation)
 import Registry.Operation as Operation
 import Run (AFF, EFFECT, Run)
 import Run as Run
@@ -86,9 +86,9 @@ runGitHubIssue env = do
   run do
     -- Determine endpoint and prepare the JSON payload
     { endpoint, jsonBody } <- case env.operation of
-      Left packageSetOp@(PackageSetUpdate payload) -> do
+      Left packageSetOp -> do
         -- Sign with pacchettibotti if submitter is a trustee
-        request <- signPackageSetIfTrustee packageSetOp payload
+        request <- signPackageSetIfTrustee packageSetOp
         pure
           { endpoint: "/v1/package-sets"
           , jsonBody: JSON.print $ CJ.encode Operation.packageSetUpdateRequestCodec request
@@ -366,7 +366,7 @@ readOperation eventPath = do
       let keys = CJ.Object.keys object
       let hasKeys = all (flip Array.elem keys)
       if hasKeys [ "packages" ] then
-        map (Left <<< PackageSetUpdate) (CJ.decode Operation.packageSetUpdateCodec json)
+        map Left (CJ.decode Operation.packageSetOperationCodec json)
       else if hasKeys [ "name", "ref", "version" ] then
         map (Right <<< Publish) (CJ.decode Operation.publishCodec json)
       else if hasKeys [ "payload", "signature" ] then
@@ -378,7 +378,7 @@ readOperation eventPath = do
           , "Received keys: " <> String.joinWith ", " keys
           , ""
           , "Expected one of:"
-          , "  - Package set update: { packages, compiler? }"
+          , "  - Package set update: { packages, compiler?, expectedBaseline? }"
           , "  - Publish: { name, ref, compiler?, version, location?, resolutions? }"
           , "  - Authenticated (unpublish/transfer): { payload, signature }"
           ]
@@ -473,10 +473,9 @@ signPacchettiBottiIfTrustee auth = do
 signPackageSetIfTrustee
   :: forall r
    . PackageSetOperation
-  -> Operation.PackageSetUpdateData
   -> Run (GITHUB + PACCHETTIBOTTI_ENV + GITHUB_EVENT_ENV + LOG + EXCEPT String + r) Operation.PackageSetUpdateRequest
-signPackageSetIfTrustee packageSetOp payload = do
-  let rawPayload = JSON.print $ CJ.encode Operation.packageSetUpdateCodec payload
+signPackageSetIfTrustee packageSetOp = do
+  let rawPayload = JSON.print $ CJ.encode Operation.packageSetOperationCodec packageSetOp
   GitHub.listTeamMembers API.packagingTeam >>= case _ of
     Left githubError -> do
       Log.warn $ Array.fold
diff --git a/app/src/App/Server/Router.purs b/app/src/App/Server/Router.purs
index 090e348b..08970c3f 100644
--- a/app/src/App/Server/Router.purs
+++ b/app/src/App/Server/Router.purs
@@ -20,7 +20,6 @@ import Registry.App.Effect.Db as Db
 import Registry.App.Effect.Env as Env
 import Registry.App.Effect.Log as Log
 import Registry.App.Server.Env (ServerEffects, ServerEnv, jsonCreated, jsonDecoder, jsonOk, runEffects)
-import Registry.Operation (PackageSetOperation(..))
 import Registry.Operation as Operation
 import Run (Run)
 import Run as Run
@@ -165,7 +164,7 @@ router { route, method, body } = HTTPurple.usingCont case route, method of
 
     -- Check if the operation requires authentication (compiler change or package removal)
     let
-      PackageSetUpdate payload = request.payload
+      payload = Operation.packageSetUpdateData request.payload
       didChangeCompiler = isJust payload.compiler
       didRemovePackages = any isNothing payload.packages
       requiresAuth = didChangeCompiler || didRemovePackages
diff --git a/app/test/App/API.purs b/app/test/App/API.purs
index 0ecd69fd..05385448 100644
--- a/app/test/App/API.purs
+++ b/app/test/App/API.purs
@@ -15,10 +15,13 @@ import Effect.Ref as Ref
 import Node.FS.Aff as FS.Aff
 import Node.Path as Path
 import Node.Process as Process
+import Registry.API.V1 (JobId(..), PackageSetJobData)
 import Registry.App.API (LicenseValidationError(..), validateLicense)
 import Registry.App.API as API
 import Registry.App.Effect.Env as Env
 import Registry.App.Effect.Log as Log
+import Registry.App.Effect.PackageSets (Change(..))
+import Registry.App.Effect.PackageSets as PackageSets
 import Registry.App.Effect.Pursuit as Pursuit
 import Registry.App.Effect.Registry as Registry
 import Registry.App.Effect.Storage as Storage
@@ -29,7 +32,8 @@ import Registry.Foreign.FastGlob as FastGlob
 import Registry.Foreign.Tmp as Tmp
 import Registry.License as License
 import Registry.Location (Location(..))
-import Registry.Operation (PublishData)
+import Registry.ManifestIndex as ManifestIndex
+import Registry.Operation (PackageSetOperation(..), PackageSetUpdateData, PublishData)
 import Registry.PackageName as PackageName
 import Registry.Test.Assert as Assert
 import Registry.Test.Assert.Run as Assert.Run
@@ -39,6 +43,7 @@ import Run (EFFECT, Run)
 import Run as Run
 import Run.Except as Except
 import Test.Spec as Spec
+import Type.Proxy (Proxy(..))
 
 -- | The environment accessible to each assertion in the test suite, derived
 -- | from the fixtures.
@@ -131,6 +136,9 @@ spec = do
   Spec.describe "Verifies build plans" do
     checkBuildPlanToResolutions
 
+  Spec.describe "Applies package set updates" do
+    packageSetUpdateSpec
+
   Spec.describe "Parses source manifests" do
     parseSourceManifestSpec
 
@@ -359,6 +367,143 @@ spec = do
         , githubDir: Path.concat [ testFixtures, "github-packages" ]
         }
 
+type PackageSetUpdateCalls =
+  { atomicChanges :: Array PackageSets.ChangeSet
+  , sequentialCompiles :: Int
+  , writes :: Int
+  , mirrors :: Int
+  }
+
+packageSetUpdateSpec :: Spec.Spec Unit
+packageSetUpdateSpec = do
+  Spec.it "rejects a stale expected baseline before validation, compilation, or publication" do
+    let operation = PackageSetUpdateFrom (Utils.unsafeVersion "1.0.0") packageSetUpdateData
+    { calls, result } <- liftEffect $ runPackageSetUpdate operation
+
+    case result of
+      Left error -> error `Assert.shouldSatisfy` String.contains (Pattern "expected baseline 1.0.0, but the latest package set is 1.0.1")
+      Right _ -> Assert.fail "Expected a stale package set update to fail."
+    calls `Assert.shouldEqual` emptyPackageSetUpdateCalls
+
+  Spec.it "does not publish a sequential subset when the exact update fails to compile" do
+    let
+      operation = PackageSetUpdateFrom (Utils.unsafeVersion "1.0.1") packageSetUpdateData
+      expectedChanges = packageSetUpdateData.packages <#> maybe Remove Update
+    { calls, result } <- liftEffect $ runPackageSetUpdate operation
+
+    case result of
+      Left error -> error `Assert.shouldSatisfy` String.contains (Pattern "failed to compile atomically")
+      Right _ -> Assert.fail "Expected an atomically failing package set update to fail."
+    calls `Assert.shouldEqual` emptyPackageSetUpdateCalls { atomicChanges = [ expectedChanges ] }
+
+emptyPackageSetUpdateCalls :: PackageSetUpdateCalls
+emptyPackageSetUpdateCalls = { atomicChanges: [], sequentialCompiles: 0, writes: 0, mirrors: 0 }
+
+runPackageSetUpdate
+  :: PackageSetOperation
+  -> Effect { calls :: PackageSetUpdateCalls, result :: Either String Unit }
+runPackageSetUpdate operation = do
+  callsRef <- Ref.new emptyPackageSetUpdateCalls
+  result <- API.packageSetUpdate (packageSetJob operation)
+    # Registry.interpretWrite (handlePackageSetRegistryWrite callsRef)
+    # Registry.interpretRead handlePackageSetRegistryRead
+    # PackageSets.interpret (handlePackageSetCompileFailure callsRef)
+    # Log.interpret (\(Log.Log _ _ next) -> pure next)
+    # Except.runExcept
+    # Run.runBaseEffect
+  calls <- Ref.read callsRef
+  pure { calls, result }
+
+packageSetJob :: PackageSetOperation -> PackageSetJobData
+packageSetJob payload =
+  { jobId: JobId "package-set-update-test"
+  , jobType: Proxy
+  , createdAt: Utils.unsafeDateTime "2026-07-27T00:00:00.000Z"
+  , startedAt: Nothing
+  , finishedAt: Nothing
+  , success: false
+  , logs: []
+  , payload
+  }
+
+packageSetUpdateData :: PackageSetUpdateData
+packageSetUpdateData =
+  { compiler: Nothing
+  , packages: Map.fromFoldable
+      [ Tuple (Utils.unsafePackageName "aff") (Just (Utils.unsafeVersion "2.0.0"))
+      , Tuple (Utils.unsafePackageName "prelude") (Just (Utils.unsafeVersion "2.0.0"))
+      ]
+  }
+
+latestPackageSet :: PackageSet
+latestPackageSet = PackageSet
+  { compiler: Utils.unsafeVersion "0.15.15"
+  , packages: Map.fromFoldable
+      [ Tuple (Utils.unsafePackageName "aff") (Utils.unsafeVersion "1.0.0")
+      , Tuple (Utils.unsafePackageName "prelude") (Utils.unsafeVersion "1.0.0")
+      ]
+  , published: Utils.unsafeDate "2026-07-26"
+  , version: Utils.unsafeVersion "1.0.1"
+  }
+
+packageSetUpdateIndex :: ManifestIndex
+packageSetUpdateIndex = unsafeFromRight $ ManifestIndex.fromSet ManifestIndex.IgnoreRanges $ Set.fromFoldable
+  [ Utils.unsafeManifest "aff" "1.0.0" []
+  , Utils.unsafeManifest "aff" "2.0.0" []
+  , Utils.unsafeManifest "prelude" "1.0.0" []
+  , Utils.unsafeManifest "prelude" "2.0.0" []
+  ]
+
+handlePackageSetCompileFailure
+  :: forall r a
+   . Ref PackageSetUpdateCalls
+  -> PackageSets.PackageSets a
+  -> Run (EFFECT + r) a
+handlePackageSetCompileFailure callsRef = case _ of
+  PackageSets.UpgradeAtomic _ _ changes reply -> do
+    Run.liftEffect $ Ref.modify_ (\calls -> calls { atomicChanges = calls.atomicChanges <> [ changes ] }) callsRef
+    pure $ reply $ Right $ Left "injected multi-package compilation failure"
+  PackageSets.UpgradeSequential _ _ _ reply -> do
+    Run.liftEffect $ Ref.modify_ (\calls -> calls { sequentialCompiles = calls.sequentialCompiles + 1 }) callsRef
+    pure $ reply $ Right Nothing
+
+handlePackageSetRegistryRead
+  :: forall r a
+   . Registry.RegistryRead a
+  -> Run r a
+handlePackageSetRegistryRead = case _ of
+  Registry.ReadManifest name version reply ->
+    pure $ reply $ Right $ ManifestIndex.lookup name version packageSetUpdateIndex
+  Registry.ReadAllManifests reply ->
+    pure $ reply $ Right packageSetUpdateIndex
+  Registry.ReadMetadata _ reply ->
+    pure $ reply $ Right Nothing
+  Registry.ReadAllMetadata reply ->
+    pure $ reply $ Right Map.empty
+  Registry.ReadLatestPackageSet reply ->
+    pure $ reply $ Right $ Just latestPackageSet
+  Registry.ReadAllPackageSets reply ->
+    pure $ reply $ Right $ Map.singleton (un PackageSet latestPackageSet).version latestPackageSet
+
+handlePackageSetRegistryWrite
+  :: forall r a
+   . Ref PackageSetUpdateCalls
+  -> Registry.RegistryWrite a
+  -> Run (EFFECT + r) a
+handlePackageSetRegistryWrite callsRef = case _ of
+  Registry.WriteManifest _ reply ->
+    pure $ reply $ Right unit
+  Registry.DeleteManifest _ _ reply ->
+    pure $ reply $ Right unit
+  Registry.WriteMetadata _ _ reply ->
+    pure $ reply $ Right unit
+  Registry.WritePackageSet _ _ reply -> do
+    Run.liftEffect $ Ref.modify_ (\calls -> calls { writes = calls.writes + 1 }) callsRef
+    pure $ reply $ Right unit
+  Registry.MirrorPackageSet _ reply -> do
+    Run.liftEffect $ Ref.modify_ (\calls -> calls { mirrors = calls.mirrors + 1 }) callsRef
+    pure $ reply $ Right unit
+
 checkBuildPlanToResolutions :: Spec.Spec Unit
 checkBuildPlanToResolutions = do
   Spec.it "buildPlanToResolutions produces expected resolutions file format" do
diff --git a/lib/src/Operation.purs b/lib/src/Operation.purs
index 727f0482..ed92d134 100644
--- a/lib/src/Operation.purs
+++ b/lib/src/Operation.purs
@@ -26,6 +26,8 @@ module Registry.Operation
   , authenticatedCodec
   , packageName
   , packageOperationCodec
+  , packageSetUpdateData
+  , packageSetUpdateExpectedBaseline
   , packageSetOperationCodec
   , packageSetUpdateCodec
   , packageSetUpdateRequestCodec
@@ -45,7 +47,7 @@ import Data.Codec.JSON as CJ
 import Data.Codec.JSON.Common as CJ.Common
 import Data.Codec.JSON.Record as CJ.Record
 import Data.Map (Map)
-import Data.Maybe (Maybe)
+import Data.Maybe (Maybe(..))
 import JSON as JSON
 import Registry.Internal.Codec as Internal.Codec
 import Registry.LimitedString (LimitedString)
@@ -201,8 +203,13 @@ transferCodec = CJ.named "Transfer" $ CJ.Record.object
   , newLocation: Location.codec
   }
 
--- | An operation that affects the package sets.
-data PackageSetOperation = PackageSetUpdate PackageSetUpdateData
+-- | An operation that affects the package sets. `PackageSetUpdateFrom` binds
+-- | the update to the given expected latest package set version, while the
+-- | original `PackageSetUpdate` constructor remains available for backwards
+-- | compatibility with manually-created operations.
+data PackageSetOperation
+  = PackageSetUpdate PackageSetUpdateData
+  | PackageSetUpdateFrom Version PackageSetUpdateData
 
 derive instance Eq PackageSetOperation
 
@@ -210,8 +217,42 @@ derive instance Eq PackageSetOperation
 packageSetOperationCodec :: CJ.Codec PackageSetOperation
 packageSetOperationCodec = CJ.named "PackageSetOperation" $ Codec.codec' decode encode
   where
-  decode json = map PackageSetUpdate (Codec.decode packageSetUpdateCodec json)
-  encode (PackageSetUpdate update) = CJ.encode packageSetUpdateCodec update
+  decode json = do
+    update <- Codec.decode packageSetOperationRepCodec json
+    pure case update.expectedBaseline of
+      Nothing -> PackageSetUpdate { compiler: update.compiler, packages: update.packages }
+      Just version -> PackageSetUpdateFrom version { compiler: update.compiler, packages: update.packages }
+
+  encode operation = CJ.encode packageSetOperationRepCodec case operation of
+    PackageSetUpdate update ->
+      { expectedBaseline: Nothing, compiler: update.compiler, packages: update.packages }
+    PackageSetUpdateFrom version update ->
+      { expectedBaseline: Just version, compiler: update.compiler, packages: update.packages }
+
+  packageSetOperationRepCodec
+    :: CJ.Codec
+         { expectedBaseline :: Maybe Version
+         , compiler :: Maybe Version
+         , packages :: Map PackageName (Maybe Version)
+         }
+  packageSetOperationRepCodec = CJ.Record.object
+    { expectedBaseline: CJ.Record.optional Version.codec
+    , compiler: CJ.Record.optional Version.codec
+    , packages: Internal.Codec.packageMap (CJ.Common.nullable Version.codec)
+    }
+
+-- | Retrieve the compiler and package changes from a package set operation.
+packageSetUpdateData :: PackageSetOperation -> PackageSetUpdateData
+packageSetUpdateData = case _ of
+  PackageSetUpdate update -> update
+  PackageSetUpdateFrom _ update -> update
+
+-- | Retrieve the expected latest package set version, when the operation is
+-- | bound to a baseline.
+packageSetUpdateExpectedBaseline :: PackageSetOperation -> Maybe Version
+packageSetUpdateExpectedBaseline = case _ of
+  PackageSetUpdate _ -> Nothing
+  PackageSetUpdateFrom version _ -> Just version
 
 -- | Submit a batch update to the most recent package set.
 -- |
@@ -222,7 +263,8 @@ type PackageSetUpdateData =
   , packages :: Map PackageName (Maybe Version)
   }
 
--- | A codec for encoding and decoding a `PackageSetUpdate` operation as JSON.
+-- | A backwards-compatible codec for unbound `PackageSetUpdate` data. Use
+-- | `packageSetOperationCodec` to encode or decode an `expectedBaseline`.
 packageSetUpdateCodec :: CJ.Codec PackageSetUpdateData
 packageSetUpdateCodec = CJ.named "PackageSetUpdate" $ CJ.Record.object
   { compiler: CJ.Record.optional Version.codec
diff --git a/lib/test/Registry/Operation.purs b/lib/test/Registry/Operation.purs
index 1400e70e..f7041ed3 100644
--- a/lib/test/Registry/Operation.purs
+++ b/lib/test/Registry/Operation.purs
@@ -15,6 +15,13 @@ spec = do
       , { label: "update-full", value: fullPackageSetUpdate }
       ]
 
+  Spec.it "Round-trips package set operations with and without an expected baseline" do
+    Assert.shouldRoundTrip "Package Set Operation" Operation.packageSetOperationCodec
+      [ { label: "update-unbound-minimal", value: minimalPackageSetUpdate }
+      , { label: "update-unbound-full", value: fullPackageSetUpdate }
+      , { label: "update-baseline-bound", value: baselineBoundPackageSetUpdate }
+      ]
+
   Spec.it "Round-trips publish fixtures" do
     Assert.shouldRoundTrip "Publish" Operation.publishCodec
       [ { label: "publish-minimal", value: minimalPublish }
@@ -48,6 +55,17 @@ fullPackageSetUpdate =
   }
 }"""
 
+baselineBoundPackageSetUpdate :: String
+baselineBoundPackageSetUpdate =
+  """
+{
+  "expectedBaseline": "68.1.1",
+  "packages": {
+    "aff": "9.0.0",
+    "argonaut": "10.0.0"
+  }
+}"""
+
 minimalPublish :: String
 minimalPublish =
   """
diff --git a/scripts/spago.yaml b/scripts/spago.yaml
index 76d33506..f6715872 100644
--- a/scripts/spago.yaml
+++ b/scripts/spago.yaml
@@ -14,6 +14,7 @@ package:
     - fetch
     - foldable-traversable
     - formatters
+    - integers
     - json
     - node-fs
     - node-path
diff --git a/scripts/src/PackageSetPlanner.purs b/scripts/src/PackageSetPlanner.purs
new file mode 100644
index 00000000..093b4c7a
--- /dev/null
+++ b/scripts/src/PackageSetPlanner.purs
@@ -0,0 +1,706 @@
+-- | Compile-guided planning for package set updates.
+-- |
+-- | The planner first tries every latest candidate together. If that fails,
+-- | manifest dependency *names* split candidates into interaction components;
+-- | declared ranges never decide eligibility. Each component is searched
+-- | best-first over latest, intermediate, and current choices, preferring more
+-- | upgrades and then fresher versions. A failed node branches by stepping one
+-- | package to its next choice. Component results are combined best-first, and
+-- | every returned automatic payload receives a final exact whole-set compile.
+-- |
+-- | Both searches have strict probe budgets. Exhausting one marks the result
+-- | truncated (possibly non-maximal), but never verified unless its exact
+-- | payload compiled. Residual latest updates are probed for the manual lane;
+-- | compiler source paths seed reverse-dependency removal closure, and a
+-- | removal is called verified only after that exact payload also compiles.
+-- | Infrastructure failures are kept separate from compiler incompatibility.
+module Registry.Scripts.PackageSetPlanner where
+
+import Registry.App.Prelude
+
+import Data.Array as Array
+import Data.Foldable as Foldable
+import Data.Map as Map
+import Data.Set as Set
+import Data.String as String
+import Registry.App.Effect.PackageSets (PACKAGE_SETS)
+import Registry.App.Effect.PackageSets as PackageSets
+import Registry.Manifest (Manifest(..))
+import Registry.ManifestIndex (ManifestIndex)
+import Registry.ManifestIndex as ManifestIndex
+import Registry.Metadata (Metadata(..))
+import Registry.PackageName (PackageName)
+import Registry.PackageName as PackageName
+import Registry.PackageSet (PackageSet(..))
+import Registry.Version (Version)
+import Run (Run)
+import Run.Except (EXCEPT)
+import Run.Except as Except
+
+type Candidate =
+  { current :: Maybe Version
+  , name :: PackageName
+  , versions :: Array Version
+  }
+
+type Verification =
+  { error :: Maybe String
+  , status :: String
+  }
+
+type AutomaticPlan =
+  { attempts :: Int
+  , packages :: Map PackageName Version
+  , searchTruncated :: Boolean
+  , verification :: Verification
+  }
+
+type ManualIntervention =
+  { compilerError :: Maybe String
+  , packages :: Map PackageName Version
+  , removals :: Array PackageName
+  , verification :: Verification
+  }
+
+type Plan =
+  { automatic :: AutomaticPlan
+  , manualError :: Maybe String
+  , manualInterventions :: Array ManualIntervention
+  , manualSearchTruncated :: Boolean
+  }
+
+data ProbeResult
+  = Compiles
+  | CompilationFailure String
+  | InfrastructureFailure String
+
+derive instance Eq ProbeResult
+
+type Probe r = PackageSet -> PackageSets.ChangeSet -> Run r ProbeResult
+
+automaticProbeBudget :: Int
+automaticProbeBudget = 64
+
+componentProbeBudget :: Int
+componentProbeBudget = 12
+
+aggregateProbeReserve :: Int
+aggregateProbeReserve = 8
+
+manualProbeBudget :: Int
+manualProbeBudget = 32
+
+-- | All newer published versions remain available to the planner. Compiler
+-- | metadata and manifest ranges are deliberately not eligibility filters.
+existingPackageCandidates :: PackageSet -> Map PackageName Metadata -> Array Candidate
+existingPackageCandidates (PackageSet packageSet) metadata = Array.mapMaybe toCandidate (Map.toUnfoldable packageSet.packages)
+  where
+  toCandidate (Tuple name current) = do
+    Metadata packageMetadata <- Map.lookup name metadata
+    let versions = packageMetadata.published # Map.keys # Array.fromFoldable # Array.filter (_ > current) # Array.sort # Array.reverse
+    guard $ not (Array.null versions)
+    pure { current: Just current, name, versions }
+
+-- | Turn a latest-only batch (including recent additions) into planner input.
+candidatesFromLatest :: PackageSet -> Map PackageName Version -> Array Candidate
+candidatesFromLatest (PackageSet packageSet) latest = do
+  Tuple name version <- Map.toUnfoldable latest
+  let current = Map.lookup name packageSet.packages
+  guard $ maybe true (_ < version) current
+  pure { current, name, versions: [ version ] }
+
+planPackageSet
+  :: forall r
+   . PackageSet
+  -> ManifestIndex
+  -> Array Candidate
+  -> Run (PACKAGE_SETS + EXCEPT String + r) Plan
+planPackageSet = planPackageSetWith probeAtomic
+
+planAutomatic
+  :: forall r
+   . PackageSet
+  -> ManifestIndex
+  -> Array Candidate
+  -> Run (PACKAGE_SETS + EXCEPT String + r) AutomaticPlan
+planAutomatic packageSet manifests candidates = _.automatic <$> planAutomaticWith probeAtomic packageSet manifests candidates
+
+probeAtomic
+  :: forall r
+   . Probe (PACKAGE_SETS + EXCEPT String + r)
+probeAtomic packageSet changes =
+  Except.runExcept (PackageSets.upgradeAtomic packageSet (un PackageSet packageSet).compiler changes) >>= case _ of
+    Left error -> pure $ InfrastructureFailure error
+    Right (Left error) -> pure $ CompilationFailure error
+    Right (Right _) -> pure Compiles
+
+planPackageSetWith
+  :: forall r
+   . Probe r
+  -> PackageSet
+  -> ManifestIndex
+  -> Array Candidate
+  -> Run r Plan
+planPackageSetWith probe packageSet manifests candidates = do
+  let checkedProbe = selfContainedProbe manifests probe
+  automaticResult <- planAutomaticWithChecked checkedProbe packageSet manifests candidates
+  let automatic = automaticResult.automatic
+  manual <-
+    if automatic.verification.status == "infrastructure-failed" then
+      pure emptyManualState
+    else
+      planManualInterventions checkedProbe packageSet manifests automaticResult.components automatic
+  pure
+    { automatic
+    , manualError: manual.error
+    , manualInterventions: manual.interventions
+    , manualSearchTruncated: manual.truncated
+    }
+
+type AutomaticResult =
+  { automatic :: AutomaticPlan
+  , components :: Array (Array Candidate)
+  }
+
+type ComponentPlan =
+  { packages :: Map PackageName Version }
+
+planAutomaticWith
+  :: forall r
+   . Probe r
+  -> PackageSet
+  -> ManifestIndex
+  -> Array Candidate
+  -> Run r AutomaticResult
+planAutomaticWith probe packageSet manifests candidates =
+  planAutomaticWithChecked (selfContainedProbe manifests probe) packageSet manifests candidates
+
+planAutomaticWithChecked
+  :: forall r
+   . Probe r
+  -> PackageSet
+  -> ManifestIndex
+  -> Array Candidate
+  -> Run r AutomaticResult
+planAutomaticWithChecked probe packageSet manifests candidates
+  | Just error <- validateCandidates packageSet candidates = pure
+      { automatic:
+          { attempts: 0
+          , packages: Map.empty
+          , searchTruncated: false
+          , verification: { error: Just error, status: "infrastructure-failed" }
+          }
+      , components: []
+      }
+  | Array.null candidates = pure
+      { automatic:
+          { attempts: 0
+          , packages: Map.empty
+          , searchTruncated: false
+          , verification: { error: Nothing, status: "not-needed" }
+          }
+      , components: []
+      }
+  | otherwise = do
+      let latest = latestUpdates candidates
+      probe packageSet (map PackageSets.Update latest) >>= case _ of
+        Compiles -> pure
+          { automatic:
+              { attempts: 1
+              , packages: latest
+              , searchTruncated: false
+              , verification: { error: Nothing, status: "verified" }
+              }
+          , components: interactionComponents packageSet manifests candidates
+          }
+        InfrastructureFailure error -> pure
+          { automatic:
+              { attempts: 1
+              , packages: Map.empty
+              , searchTruncated: false
+              , verification: { error: Just error, status: "infrastructure-failed" }
+              }
+          , components: interactionComponents packageSet manifests candidates
+          }
+        CompilationFailure _ -> do
+          let components = interactionComponents packageSet manifests candidates
+          searched <- searchComponents probe packageSet components
+          let nonemptyPlans = Array.filter (not <<< Map.isEmpty <<< _.packages) searched.plans
+          if Array.null nonemptyPlans then do
+            let
+              verification =
+                if searched.truncated then
+                  { error: Just "The bounded compatibility search was truncated; no automatic payload is submission-ready."
+                  , status: "incomplete"
+                  }
+                else { error: searched.error, status: maybe "not-needed" (const "infrastructure-failed") searched.error }
+            pure
+              { automatic:
+                  { attempts: 1 + searched.attempts
+                  , packages: Map.empty
+                  , searchTruncated: searched.truncated
+                  , verification
+                  }
+              , components
+              }
+          else case searched.error of
+            Just error -> pure
+              { automatic:
+                  { attempts: 1 + searched.attempts
+                  , packages: Map.empty
+                  , searchTruncated: searched.truncated
+                  , verification: { error: Just error, status: "infrastructure-failed" }
+                  }
+              , components
+              }
+            Nothing -> do
+              let remaining = automaticProbeBudget - 1 - searched.attempts
+              aggregate <- searchAggregate probe packageSet nonemptyPlans remaining
+              let truncated = searched.truncated || aggregate.truncated
+              pure
+                { automatic:
+                    { attempts: 1 + searched.attempts + aggregate.attempts
+                    , packages: aggregate.packages
+                    , searchTruncated: truncated
+                    -- Search truncation limits optimality, not correctness: a
+                    -- nonempty aggregate is returned only after this exact
+                    -- whole-set payload compiled successfully.
+                    , verification: aggregate.verification
+                    }
+                , components
+                }
+
+-- | Package sets ignore dependency ranges, but every selected manifest must
+-- | have all of its dependency names in the exact selected package map. Reject
+-- | malformed search nodes as compatibility failures before invoking the
+-- | compiler so validation errors can never be mistaken for infrastructure
+-- | failures or returned as verified payloads.
+selfContainedProbe :: forall r. ManifestIndex -> Probe r -> Probe r
+selfContainedProbe manifests probe packageSet@(PackageSet baseline) changes =
+  case packageSelectionError manifests baseline.packages of
+    Just error -> pure $ InfrastructureFailure $ "The current package set is not dependency-name self-contained: " <> error
+    Nothing -> case packageSelectionError manifests (applyChanges baseline.packages changes) of
+      Just error -> pure $ CompilationFailure $ "The proposed package set is not dependency-name self-contained: " <> error
+      Nothing -> probe packageSet changes
+
+applyChanges :: Map PackageName Version -> PackageSets.ChangeSet -> Map PackageName Version
+applyChanges packages changes = foldlWithIndex applyChange packages changes
+  where
+  applyChange name selected change = case change of
+    PackageSets.Remove -> Map.delete name selected
+    PackageSets.Update version -> Map.insert name version selected
+
+packageSelectionError :: ManifestIndex -> Map PackageName Version -> Maybe String
+packageSelectionError manifests selected = Array.head failures
+  where
+  failures = Array.mapMaybe checkManifest (Map.toUnfoldable selected)
+
+  checkManifest (Tuple name version) = case ManifestIndex.lookup name version manifests of
+    Nothing -> Just $ "No manifest exists for selected package " <> formatPackageVersion name version <> "."
+    Just (Manifest manifest) -> do
+      missing <- Set.findMin $ Set.difference (Map.keys manifest.dependencies) (Map.keys selected)
+      pure $ formatPackageVersion name version <> " requires missing package " <> PackageName.print missing <> "."
+
+-- | Reject malformed caller input before any compile probe. The automatic
+-- | representation is upgrade/add-only, so existing choices must be strictly
+-- | newer and every package has a nonempty, unique domain.
+validateCandidates :: PackageSet -> Array Candidate -> Maybe String
+validateCandidates (PackageSet packageSet) candidates = do
+  let names = map _.name candidates
+  let
+    invalidCurrent candidate = case Map.lookup candidate.name packageSet.packages of
+      Nothing -> isJust candidate.current
+      Just current -> candidate.current /= Just current || any (_ <= current) candidate.versions
+  if Array.length names /= Set.size (Set.fromFoldable names) then Just "Planner candidates contain duplicate package names."
+  else if any (Array.null <<< _.versions) candidates then Just "Planner candidate domains must not be empty."
+  else if any invalidCurrent candidates then Just "Existing-package candidate choices must all be strictly newer than the current version."
+  else Nothing
+
+type ComponentSearches =
+  { attempts :: Int
+  , error :: Maybe String
+  , plans :: Array ComponentPlan
+  , truncated :: Boolean
+  }
+
+searchComponents
+  :: forall r
+   . Probe r
+  -> PackageSet
+  -> Array (Array Candidate)
+  -> Run r ComponentSearches
+searchComponents probe packageSet = go
+  { attempts: 0
+  , error: Nothing
+  , plans: []
+  , truncated: false
+  }
+  where
+  go state remaining = case Array.uncons remaining of
+    Nothing -> pure state
+    Just { head: component, tail: rest }
+      | isJust state.error -> pure state
+      | otherwise -> do
+          let globallyAvailable = automaticProbeBudget - 1 - aggregateProbeReserve - state.attempts
+          let available = min componentProbeBudget (max 0 globallyAvailable)
+          if available <= 0 then
+            pure $ state
+              { plans = state.plans <> map (const { packages: Map.empty }) remaining
+              , truncated = true
+              }
+          else do
+            result <- searchCandidates probe packageSet component available
+            let
+              next = state
+                { attempts = state.attempts + result.attempts
+                , error = result.infrastructureError
+                , plans = state.plans <> [ { packages: result.packages } ]
+                , truncated = state.truncated || result.truncated
+                }
+            go next rest
+
+type CandidateSearch =
+  { attempts :: Int
+  , infrastructureError :: Maybe String
+  , packages :: Map PackageName Version
+  , truncated :: Boolean
+  }
+
+type SearchNode = Array Int
+
+searchCandidates
+  :: forall r
+   . Probe r
+  -> PackageSet
+  -> Array Candidate
+  -> Int
+  -> Run r CandidateSearch
+searchCandidates probe packageSet candidates budget = go [ initial ] (Set.singleton (nodeKey initial)) 0
+  where
+  initial = map (const 0) candidates
+
+  go frontier seen attempts
+    | attempts >= budget = pure
+        { attempts
+        , infrastructureError: Nothing
+        , packages: Map.empty
+        , truncated: not (Array.null frontier)
+        }
+    | otherwise = case Array.uncons (Array.sortBy (compareNodes candidates) frontier) of
+        Nothing -> pure
+          { attempts
+          , infrastructureError: Nothing
+          , packages: Map.empty
+          , truncated: false
+          }
+        Just { head: node, tail } -> do
+          let packages = nodeUpdates candidates node
+          if Map.isEmpty packages then
+            pure { attempts, infrastructureError: Nothing, packages: Map.empty, truncated: false }
+          else
+            probe packageSet (map PackageSets.Update packages) >>= case _ of
+              Compiles -> pure { attempts: attempts + 1, infrastructureError: Nothing, packages, truncated: false }
+              InfrastructureFailure error -> pure
+                { attempts: attempts + 1
+                , infrastructureError: Just error
+                , packages: Map.empty
+                , truncated: false
+                }
+              CompilationFailure _ -> do
+                let additions = Array.filter (nodeKey >>> flip (not Set.member) seen) (nodeNeighbours candidates node)
+                let nextSeen = Foldable.foldl (flip (Set.insert <<< nodeKey)) seen additions
+                go (tail <> additions) nextSeen (attempts + 1)
+
+type AggregateSearch =
+  { attempts :: Int
+  , packages :: Map PackageName Version
+  , truncated :: Boolean
+  , verification :: Verification
+  }
+
+searchAggregate
+  :: forall r
+   . Probe r
+  -> PackageSet
+  -> Array ComponentPlan
+  -> Int
+  -> Run r AggregateSearch
+searchAggregate probe packageSet plans budget = go [ initial ] (Set.singleton (nodeKey initial)) 0 Nothing
+  where
+  initial = map (const 0) plans
+
+  go frontier seen attempts lastError
+    | attempts >= budget = pure
+        { attempts
+        , packages: Map.empty
+        , truncated: not (Array.null frontier)
+        , verification: { error: lastError, status: "failed" }
+        }
+    | otherwise = case Array.uncons (Array.sortBy compareAggregateNodes frontier) of
+        Nothing -> pure
+          { attempts
+          , packages: Map.empty
+          , truncated: false
+          , verification: { error: lastError, status: "failed" }
+          }
+        Just { head: node, tail } -> do
+          let packages = aggregateUpdates plans node
+          if Map.isEmpty packages then
+            pure
+              { attempts
+              , packages: Map.empty
+              , truncated: false
+              , verification: { error: Nothing, status: "not-needed" }
+              }
+          else
+            probe packageSet (map PackageSets.Update packages) >>= case _ of
+              Compiles -> pure
+                { attempts: attempts + 1
+                , packages
+                , truncated: false
+                , verification: { error: Nothing, status: "verified" }
+                }
+              InfrastructureFailure error -> pure
+                { attempts: attempts + 1
+                , packages: Map.empty
+                , truncated: false
+                , verification: { error: Just error, status: "infrastructure-failed" }
+                }
+              CompilationFailure error -> do
+                let additions = Array.filter (nodeKey >>> flip (not Set.member) seen) (aggregateNeighbours node)
+                let nextSeen = Foldable.foldl (flip (Set.insert <<< nodeKey)) seen additions
+                go (tail <> additions) nextSeen (attempts + 1) (Just error)
+
+  compareAggregateNodes a b = compare (aggregateScore plans b) (aggregateScore plans a)
+
+type ManualState =
+  { attempts :: Int
+  , error :: Maybe String
+  , interventions :: Array ManualIntervention
+  , truncated :: Boolean
+  }
+
+emptyManualState :: ManualState
+emptyManualState =
+  { attempts: 0
+  , error: Nothing
+  , interventions: []
+  , truncated: false
+  }
+
+planManualInterventions
+  :: forall r
+   . Probe r
+  -> PackageSet
+  -> ManifestIndex
+  -> Array (Array Candidate)
+  -> AutomaticPlan
+  -> Run r ManualState
+planManualInterventions probe packageSet manifests components automatic = go emptyManualState residual
+  where
+  residual = Array.mapMaybe residualComponent components
+
+  residualComponent component = do
+    let latest = latestUpdates component
+    guard $ any (\(Tuple name version) -> Map.lookup name automatic.packages /= Just version) (Map.toUnfoldable latest :: Array _)
+    pure latest
+
+  go state remaining = case Array.uncons remaining of
+    Nothing -> pure state
+    Just { head: latest, tail: rest }
+      | state.attempts >= manualProbeBudget -> pure $ state { truncated = true }
+      | otherwise -> do
+          let packages = Map.union latest automatic.packages
+          let changes = map PackageSets.Update packages
+          probe packageSet changes >>= case _ of
+            Compiles ->
+              go (state { attempts = state.attempts + 1 }) rest
+            InfrastructureFailure error ->
+              pure $ state
+                { attempts = state.attempts + 1
+                , error = Just error
+                }
+            CompilationFailure compilerError -> do
+              let seeds = compilerFailurePackages packageSet packages compilerError
+              let proposed = applyUpdates packageSet packages
+              case reverseDependencyClosure proposed manifests seeds of
+                Left error -> pure $ state
+                  { attempts = state.attempts + 1
+                  , error = Just error
+                  }
+                Right closure -> do
+                  let removals = Set.difference closure (Map.keys packages)
+                  if Set.isEmpty removals then
+                    go
+                      ( state
+                          { attempts = state.attempts + 1
+                          , interventions = state.interventions <>
+                              [ { compilerError: Just compilerError
+                                , packages
+                                , removals: []
+                                , verification:
+                                    { error: Just "The compiler failure did not identify an unchanged package with a removable reverse-dependency closure."
+                                    , status: "unresolved"
+                                    }
+                                }
+                              ]
+                          }
+                      )
+                      rest
+                  else if state.attempts + 1 >= manualProbeBudget then
+                    pure $ state
+                      { attempts = state.attempts + 1
+                      , truncated = true
+                      }
+                  else do
+                    let removalChanges = Map.union (map (const PackageSets.Remove) (Map.fromFoldable (map (\name -> Tuple name unit) (Array.fromFoldable removals)))) changes
+                    probe packageSet removalChanges >>= case _ of
+                      Compiles ->
+                        go
+                          ( state
+                              { attempts = state.attempts + 2
+                              , interventions = state.interventions <>
+                                  [ { compilerError: Just compilerError
+                                    , packages
+                                    , removals: Array.fromFoldable removals
+                                    , verification: { error: Nothing, status: "verified" }
+                                    }
+                                  ]
+                              }
+                          )
+                          rest
+                      CompilationFailure error ->
+                        go
+                          ( state
+                              { attempts = state.attempts + 2
+                              , interventions = state.interventions <>
+                                  [ { compilerError: Just compilerError
+                                    , packages
+                                    , removals: Array.fromFoldable removals
+                                    , verification: { error: Just error, status: "failed" }
+                                    }
+                                  ]
+                              }
+                          )
+                          rest
+                      InfrastructureFailure error ->
+                        pure $ state
+                          { attempts = state.attempts + 2
+                          , error = Just error
+                          }
+
+latestUpdates :: Array Candidate -> Map PackageName Version
+latestUpdates = Map.fromFoldable <<< Array.mapMaybe \candidate -> Tuple candidate.name <$> Array.head candidate.versions
+
+candidateChoices :: Candidate -> Array (Maybe Version)
+candidateChoices candidate = map Just candidate.versions <> [ candidate.current ]
+
+nodeUpdates :: Array Candidate -> SearchNode -> Map PackageName Version
+nodeUpdates candidates node = Map.fromFoldable $ Array.mapMaybe identity do
+  Tuple candidate offset <- Array.zip candidates node
+  pure do
+    selected <- Array.index (candidateChoices candidate) offset >>= identity
+    guard $ candidate.current /= Just selected
+    pure $ Tuple candidate.name selected
+
+nodeNeighbours :: Array Candidate -> SearchNode -> Array SearchNode
+nodeNeighbours candidates node = Array.catMaybes $ Array.mapWithIndex step node
+  where
+  step index offset = do
+    candidate <- Array.index candidates index
+    guard $ offset + 1 < Array.length (candidateChoices candidate)
+    Array.modifyAt index (_ + 1) node
+
+compareNodes :: Array Candidate -> SearchNode -> SearchNode -> Ordering
+compareNodes candidates a b = compare (nodeScore candidates b) (nodeScore candidates a)
+
+nodeScore :: Array Candidate -> SearchNode -> Tuple Int Int
+nodeScore candidates node = Foldable.foldl add (Tuple 0 0) (Array.zip candidates node)
+  where
+  add (Tuple upgrades freshness) (Tuple candidate offset) = case Array.index (candidateChoices candidate) offset of
+    Just (Just selected) | candidate.current /= Just selected -> Tuple (upgrades + 1) (freshness + Array.length candidate.versions - offset)
+    _ -> Tuple upgrades freshness
+
+nodeKey :: SearchNode -> String
+nodeKey = String.joinWith "," <<< map show
+
+aggregateUpdates :: Array ComponentPlan -> SearchNode -> Map PackageName Version
+aggregateUpdates plans node = Foldable.foldl Map.union Map.empty do
+  Tuple plan offset <- Array.zip plans node
+  [ if offset == 0 then plan.packages else Map.empty ]
+
+aggregateNeighbours :: SearchNode -> Array SearchNode
+aggregateNeighbours node = Array.catMaybes $ Array.mapWithIndex step node
+  where
+  step index offset = do
+    guard $ offset == 0
+    Array.modifyAt index (const 1) node
+
+aggregateScore :: Array ComponentPlan -> SearchNode -> Int
+aggregateScore plans node = Foldable.sum do
+  Tuple plan offset <- Array.zip plans node
+  [ if offset == 0 then Map.size plan.packages else 0 ]
+
+interactionComponents :: PackageSet -> ManifestIndex -> Array Candidate -> Array (Array Candidate)
+interactionComponents (PackageSet packageSet) manifests candidates = map candidatesInSet (setsFromGraph graph candidateNames)
+  where
+  candidateNames = Set.fromFoldable (map _.name candidates)
+  candidateMap = Map.fromFoldable $ candidates <#> \candidate -> Tuple candidate.name candidate
+  relevantManifests = Array.catMaybes do
+    candidate <- candidates
+    version <- Array.catMaybes ([ candidate.current ] <> map Just candidate.versions)
+    [ ManifestIndex.lookup candidate.name version manifests ]
+  baselineManifests = Array.mapMaybe (\(Tuple name version) -> ManifestIndex.lookup name version manifests) (Map.toUnfoldable packageSet.packages)
+  graph = Foldable.foldl addManifest (Map.fromFoldable $ map (\name -> Tuple name Set.empty) (Array.fromFoldable candidateNames)) (baselineManifests <> relevantManifests)
+
+  addManifest edges (Manifest manifest) = do
+    let mentioned = Set.intersection candidateNames (Set.insert manifest.name (Map.keys manifest.dependencies))
+    mentioned # Foldable.foldl
+      (\next name -> Map.alter (Just <<< Set.union (Set.delete name mentioned) <<< fromMaybe Set.empty) name next)
+      edges
+
+  candidatesInSet names = Array.mapMaybe (flip Map.lookup candidateMap) (Array.fromFoldable names)
+
+setsFromGraph :: Map PackageName (Set PackageName) -> Set PackageName -> Array (Set PackageName)
+setsFromGraph graph = go []
+  where
+  go components remaining = case Set.findMin remaining of
+    Nothing -> components
+    Just seed -> do
+      let component = visit Set.empty [ seed ]
+      go (components <> [ component ]) (Set.difference remaining component)
+
+  visit seen frontier = case Array.uncons frontier of
+    Nothing -> seen
+    Just { head: name, tail: rest }
+      | Set.member name seen -> visit seen rest
+      | otherwise -> do
+          let neighbours = Array.fromFoldable $ fromMaybe Set.empty $ Map.lookup name graph
+          visit (Set.insert name seen) (rest <> neighbours)
+
+compilerFailurePackages :: PackageSet -> Map PackageName Version -> String -> Set PackageName
+compilerFailurePackages (PackageSet packageSet) updates error = Set.fromFoldable $ Array.mapMaybe match (Map.toUnfoldable packageSet.packages)
+  where
+  fileLines = Array.filter (String.contains (String.Pattern "File:")) (String.split (String.Pattern "\n") error)
+
+  match (Tuple name version) = do
+    guard $ not (Map.member name updates)
+    let path = "packages/" <> formatPackageVersion name version <> "/"
+    name <$ guard (any (String.contains (String.Pattern path)) fileLines)
+
+applyUpdates :: PackageSet -> Map PackageName Version -> Map PackageName Version
+applyUpdates (PackageSet packageSet) updates = Map.union updates packageSet.packages
+
+reverseDependencyClosure :: Map PackageName Version -> ManifestIndex -> Set PackageName -> Either String (Set PackageName)
+reverseDependencyClosure packages manifests = go
+  where
+  go removals = do
+    dependants <- Set.fromFoldable <<< Array.catMaybes <$> traverse (dependsOn removals) (Map.toUnfoldable packages)
+    let next = Set.union removals dependants
+    if next == removals then pure removals else go next
+
+  dependsOn removals (Tuple name version) = do
+    if Set.member name removals then pure Nothing
+    else case ManifestIndex.lookup name version manifests of
+      Nothing -> Left $ "Missing manifest while computing removal closure: " <> formatPackageVersion name version
+      Just (Manifest manifest) -> pure $ name <$ guard (not $ Set.isEmpty $ Set.intersection removals $ Map.keys manifest.dependencies)
diff --git a/scripts/src/PackageSetUpdater.purs b/scripts/src/PackageSetUpdater.purs
index ab9571c7..83f54666 100644
--- a/scripts/src/PackageSetUpdater.purs
+++ b/scripts/src/PackageSetUpdater.purs
@@ -17,6 +17,7 @@ import Codec.JSON.DecodeError as CJ.DecodeError
 import Data.Array as Array
 import Data.Codec.JSON as CJ
 import Data.DateTime as DateTime
+import Data.Foldable as Foldable
 import Data.Map as Map
 import Data.Time.Duration (Hours(..))
 import Effect.Aff as Aff
@@ -24,20 +25,31 @@ import Effect.Class.Console as Console
 import Fetch (Method(..))
 import Fetch as Fetch
 import JSON as JSON
+import Node.Path as Path
 import Node.Process as Process
 import Registry.API.V1 as V1
 import Registry.App.CLI.Git as Git
 import Registry.App.Effect.Cache as Cache
+import Registry.App.Effect.Env (RESOURCE_ENV)
 import Registry.App.Effect.Env as Env
 import Registry.App.Effect.Log (LOG)
 import Registry.App.Effect.Log as Log
+import Registry.App.Effect.PackageSets (PACKAGE_SETS)
 import Registry.App.Effect.PackageSets as PackageSets
 import Registry.App.Effect.Registry (REGISTRY_READ)
 import Registry.App.Effect.Registry as Registry
+import Registry.App.Effect.Storage (STORAGE)
+import Registry.App.Effect.Storage as Storage
+import Registry.Foreign.FSExtra as FS.Extra
+import Registry.Manifest (Manifest(..))
+import Registry.ManifestIndex (ManifestIndex)
+import Registry.ManifestIndex as ManifestIndex
+import Registry.Metadata (Metadata(..))
 import Registry.Operation (PackageSetOperation(..))
 import Registry.Operation as Operation
 import Registry.PackageName as PackageName
 import Registry.PackageSet (PackageSet(..))
+import Registry.Scripts.PackageSetPlanner as Planner
 import Registry.Version as Version
 import Run (AFF, EFFECT, Run)
 import Run as Run
@@ -77,6 +89,8 @@ main = launchAff_ do
   Env.loadEnvFile ".env"
   resourceEnv <- Env.lookupResourceEnv
 
+  let cache = Path.concat [ scratchDir, ".cache" ]
+  FS.Extra.ensureDirectory cache
   registryCacheRef <- Cache.newCacheRef
 
   debouncer <- Registry.newDebouncer
@@ -94,8 +108,11 @@ main = launchAff_ do
       }
 
   runPackageSetUpdater mode resourceEnv.registryApiUrl
+    # PackageSets.interpret (PackageSets.handle { workdir: scratchDir })
     # Except.runExcept
     # Registry.interpretRead (Registry.handleRead registryEnv)
+    # Storage.interpret (Storage.handleReadOnly cache)
+    # Env.runResourceEnv resourceEnv
     # Log.interpret (Log.handleTerminal Normal)
     # Run.runBaseAff'
     >>= case _ of
@@ -104,7 +121,7 @@ main = launchAff_ do
         liftEffect $ Process.exit' 1
       Right _ -> pure unit
 
-type PackageSetUpdaterEffects = (REGISTRY_READ + LOG + EXCEPT String + AFF + EFFECT + ())
+type PackageSetUpdaterEffects = (REGISTRY_READ + PACKAGE_SETS + STORAGE + RESOURCE_ENV + LOG + EXCEPT String + AFF + EFFECT + ())
 
 runPackageSetUpdater :: Mode -> URL -> Run PackageSetUpdaterEffects Unit
 runPackageSetUpdater mode registryApiUrl = do
@@ -120,60 +137,118 @@ runPackageSetUpdater mode registryApiUrl = do
   for_ latestPackageSet \packageSet -> do
     -- Find packages uploaded in the last 24 hours
     now <- nowUTC
-    newOrUpdated <- findPackageSetCandidates (RecentUploads now (Hours 24.0)) packageSet
+    metadata <- Registry.readAllMetadata
+    let newOrUpdated = selectPackageSetCandidates (RecentUploads now (Hours 24.0)) packageSet metadata
 
-    if Map.isEmpty newOrUpdated then
-      Log.info "No new packages for package set update."
+    Log.info $ "Found " <> show (Map.size newOrUpdated) <> " recent additions or upgrades"
+    manifestIndex <- Registry.readAllManifests
+    let candidates = plannerCandidates packageSet metadata manifestIndex newOrUpdated
+    if Array.null candidates then
+      Log.info "No package set candidates have usable manifests."
     else do
-      Log.info $ "Found " <> show (Map.size newOrUpdated) <> " candidates to validate"
+      Log.info $ "Compile-planning " <> show (Array.length candidates) <> " package domains"
+      plan <- Planner.planAutomatic packageSet manifestIndex candidates
+      Registry.readLatestPackageSet >>= case _ of
+        Nothing -> Log.warn "The latest package set disappeared before submission; skipping this run."
+        Just latest -> submitVerifiedPlan mode registryApiUrl packageSet latest plan
 
-      -- Pre-validate candidates to filter out packages with missing dependencies
-      manifestIndex <- Registry.readAllManifests
-      let candidates = PackageSets.validatePackageSetCandidates manifestIndex packageSet (map Just newOrUpdated)
+-- | Submit only the exact, verified, nonempty, upgrade-only payload. We still
+-- | filter stale and already-applied entries against the latest set, but refuse
+-- | to submit if filtering changed the payload because that altered payload was
+-- | not the one atomically compiled by the planner.
+submitVerifiedPlan
+  :: forall r
+   . Mode
+  -> URL
+  -> PackageSet
+  -> PackageSet
+  -> Planner.AutomaticPlan
+  -> Run (LOG + EXCEPT String + AFF + r) Unit
+submitVerifiedPlan mode registryApiUrl baseline latest plan = do
+  let applicable = filterApplicableUpgrades latest plan.packages
+  let samePackageSet = baseline == latest
+  if not samePackageSet then
+    Except.throw "The package set changed after planning; refusing to submit or report decisions without replanning."
+  else if plan.verification.status /= "verified" then
+    Log.warn $ "Package set plan is not verified (" <> plan.verification.status <> "); not submitting."
+  else if Map.isEmpty applicable then
+    Log.info "The verified package set plan is empty or already applied; nothing to submit."
+  else if applicable /= plan.packages then
+    Except.throw "Filtering changed the verified package set payload; refusing to submit an altered payload without replanning."
+  else do
+    let expectedBaseline = (un PackageSet baseline).version
+    let
+      payload :: Operation.PackageSetUpdateData
+      payload =
+        { compiler: Nothing
+        , packages: map Just applicable
+        }
+      operation = PackageSetUpdateFrom expectedBaseline payload
+    case mode of
+      DryRun -> do
+        Log.info "[DRY RUN] Would submit verified package set updates:"
+        for_ (Map.toUnfoldable applicable :: Array _) \(Tuple name version) ->
+          Log.info $ "  - " <> PackageName.print name <> "@" <> Version.print version
+      Submit -> do
+        let
+          rawPayload = JSON.print $ CJ.encode Operation.packageSetOperationCodec operation
+
+          request :: Operation.PackageSetUpdateRequest
+          request =
+            { payload: operation
+            , rawPayload
+            , signature: Nothing
+            }
+        Log.info "Submitting verified package set update..."
+        result <- Run.liftAff $ submitPackageSetJob (registryApiUrl <> "/v1/package-sets") request
+        case result of
+          Left err -> Except.throw $ "Failed to submit package set job: " <> err
+          Right { jobId } -> do
+            Log.info $ "Submitted package set job " <> unwrap jobId <> "; waiting for publication..."
+            Run.liftAff (pollPackageSetJob registryApiUrl jobId) >>= case _ of
+              Left err -> Except.throw err
+              Right _ -> Log.notice $ "Package set job " <> unwrap jobId <> " completed successfully."
 
-      unless (Map.isEmpty candidates.rejected) do
-        Log.info $ "Some packages are not eligible for the package set:\n" <> PackageSets.printRejections candidates.rejected
+-- | Drop additions/upgrades that are equal to or older than the latest set.
+filterApplicableUpgrades :: PackageSet -> Map PackageName Version -> Map PackageName Version
+filterApplicableUpgrades (PackageSet packageSet) = Map.filterWithKey \name version ->
+  maybe true (_ < version) (Map.lookup name packageSet.packages)
 
-      -- Only include accepted packages (filter out removals, keep only updates)
-      let accepted = Map.catMaybes candidates.accepted
+-- | Existing packages contribute every newer release. Recent uploads seed
+-- | additions, which are expanded by absent dependency-name closure. Declared
+-- | ranges and compiler publication metadata are deliberately not gates.
+plannerCandidates :: PackageSet -> Map PackageName Metadata -> ManifestIndex -> Map PackageName Version -> Array Planner.Candidate
+plannerCandidates packageSet@(PackageSet set) metadata manifests recent =
+  existingCandidates <> additionCandidates
+  where
+  existingCandidates = Array.mapMaybe withManifestVersions $ Planner.existingPackageCandidates packageSet metadata
+  existingDependencies = Array.concatMap (\candidate -> dependenciesOf (Tuple candidate.name candidate.versions)) existingCandidates
+  seeds = map Array.singleton $ Map.filterWithKey (\name _ -> not $ Map.member name set.packages) recent
+  additions = close seeds
+  additionCandidates = Map.toUnfoldable additions <#> \(Tuple name versions) ->
+    { current: Nothing, name, versions }
 
-      if Map.isEmpty accepted then
-        Log.info "No packages passed validation for package set update."
-      else do
-        Log.info $ "Validated " <> show (Map.size accepted) <> " packages for package set update"
+  withManifestVersions candidate = do
+    let versions = Array.filter (\version -> isJust $ ManifestIndex.lookup candidate.name version manifests) candidate.versions
+    candidate { versions = versions } <$ guard (not $ Array.null versions)
 
-        -- Create a package set update payload
-        let
-          payload :: Operation.PackageSetUpdateData
-          payload =
-            { compiler: Nothing -- Use current compiler
-            , packages: map Just accepted -- Just version = add/update
-            }
+  close selected = do
+    let dependencies = existingDependencies <> Array.concatMap dependenciesOf (Map.toUnfoldable selected)
+    let missing = Array.filter (\name -> not (Map.member name set.packages) && not (Map.member name selected)) dependencies
+    let next = Foldable.foldl addLatest selected missing
+    if next == selected then selected else close next
 
-        case mode of
-          DryRun -> do
-            Log.info $ "[DRY RUN] Would submit package set update with packages:"
-            for_ (Map.toUnfoldable accepted :: Array _) \(Tuple name version) ->
-              Log.info $ "  - " <> PackageName.print name <> "@" <> Version.print version
-
-          Submit -> do
-            let
-              rawPayload = JSON.print $ CJ.encode Operation.packageSetUpdateCodec payload
-
-              request :: Operation.PackageSetUpdateRequest
-              request =
-                { payload: PackageSetUpdate payload
-                , rawPayload
-                , signature: Nothing
-                }
-
-            Log.info $ "Submitting package set update..."
-            result <- Run.liftAff $ submitPackageSetJob (registryApiUrl <> "/v1/package-sets") request
-            case result of
-              Left err -> do
-                Log.error $ "Failed to submit package set job: " <> err
-              Right { jobId } -> do
-                Log.info $ "Submitted package set job " <> unwrap jobId
+  dependenciesOf (Tuple name versions) = Array.concatMap dependenciesAt versions
+    where
+    dependenciesAt selected = case ManifestIndex.lookup name selected manifests of
+      Nothing -> []
+      Just (Manifest manifest) -> Array.fromFoldable $ Map.keys manifest.dependencies
+
+  addLatest selected name = case Map.lookup name metadata of
+    Nothing -> selected
+    Just (Metadata packageMetadata) -> do
+      let manifested = Array.filter (\version -> isJust $ ManifestIndex.lookup name version manifests) (Map.keys packageMetadata.published # Array.fromFoldable) # Array.sort # Array.reverse
+      if Array.null manifested then selected else Map.insert name manifested selected
 
 -- | Find the latest eligible registry version for each package relative to the
 -- | current package set.
@@ -228,3 +303,51 @@ submitPackageSetJob url request = do
           Right r -> pure $ Right r
       else
         pure $ Left $ "HTTP " <> show response.status <> ": " <> responseBody
+
+-- | Wait for the server-side exact recompile and publication to finish. The
+-- | workflow must not report success merely because a durable job was queued.
+pollPackageSetJob :: String -> V1.JobId -> Aff (Either String Unit)
+pollPackageSetJob registryApiUrl jobId = go 1 0
+  where
+  maxAttempts = 720
+  maxConsecutiveErrors = 5
+  interval = Aff.Milliseconds 5_000.0
+  url = registryApiUrl <> "/v1/jobs/" <> unwrap jobId <> "?level=NOTICE"
+
+  go attempt consecutiveErrors
+    | attempt > maxAttempts =
+        pure $ Left $ "Package set job " <> unwrap jobId <> " did not finish within 60 minutes."
+    | otherwise = do
+        result <- fetchPackageSetJob url
+        case result of
+          Left error
+            | consecutiveErrors + 1 >= maxConsecutiveErrors ->
+                pure $ Left $ "Could not poll package set job " <> unwrap jobId <> " after " <> show maxConsecutiveErrors <> " consecutive errors: " <> error
+            | otherwise -> do
+                Aff.delay interval
+                go (attempt + 1) (consecutiveErrors + 1)
+          Right job -> do
+            let info = V1.jobInfo job
+            case info.finishedAt of
+              Nothing -> do
+                Aff.delay interval
+                go (attempt + 1) 0
+              Just _ | info.success ->
+                pure $ Right unit
+              Just _ -> do
+                let logs = Foldable.foldMap (\line -> "\n" <> line.message) info.logs
+                pure $ Left $ "Package set job " <> unwrap jobId <> " failed:" <> logs
+
+fetchPackageSetJob :: String -> Aff (Either String V1.Job)
+fetchPackageSetJob url = do
+  result <- Aff.attempt $ Fetch.fetch url { method: GET }
+  case result of
+    Left err -> pure $ Left $ "Network error: " <> Aff.message err
+    Right response -> do
+      responseBody <- response.text
+      if response.status >= 200 && response.status < 300 then
+        case JSON.parse responseBody >>= \json -> lmap CJ.DecodeError.print (CJ.decode V1.jobCodec json) of
+          Left err -> pure $ Left $ "Failed to parse package set job: " <> err
+          Right job -> pure $ Right job
+      else
+        pure $ Left $ "HTTP " <> show response.status <> ": " <> responseBody
diff --git a/scripts/src/VersionCheck.purs b/scripts/src/VersionCheck.purs
index eec62d62..3fc3b0f0 100644
--- a/scripts/src/VersionCheck.purs
+++ b/scripts/src/VersionCheck.purs
@@ -1,27 +1,12 @@
--- | Report registry versions newer than those in the latest package set and
--- | plan a compatible set of upgrades.
+-- | Compile pending package versions with the exact current package set
+-- | compiler, report an atomically verified automatic plan, and describe
+-- | residual updates that need manual intervention.
 -- |
--- | Packages that have never appeared in a package set are intentionally not
--- | included; discovering those packages is tracked as separate follow-up work.
--- | Planning is conservative: a release is eligible only after its metadata
--- | records a successful build with the package set compiler.
--- |
--- | Each pending package is a variable whose choices are its current version
--- | and all eligible newer versions. A bounded branch-and-bound search visits
--- | newer choices first and maximizes, in order, the number of upgraded packages
--- | and their cumulative freshness. Partial dependency-range checks prune
--- | impossible branches. Existing range mismatches are tolerated only when both
--- | ends of the dependency edge remain unchanged because historical package sets
--- | can contain stale declared bounds despite having compiled successfully.
--- |
--- | The search has a fixed node budget so the weekly report cannot hang on a
--- | pathological candidate graph, and any truncation is explicit in the report.
--- | The optional verification atomically compiles the exact planned payload but
--- | never publishes it.
+-- | Dependency ranges are advisory diagnostics only. Package set compilation
+-- | is the compatibility authority.
 -- |
 -- | Run via Nix:
--- |   nix run .#version-check
--- |   nix run .#version-check -- --verify --output report.json --markdown report.md
+-- |   nix run .#version-check -- --output report.json --markdown report.md
 module Registry.Scripts.VersionCheck where
 
 import Registry.App.Prelude
@@ -39,8 +24,9 @@ import Data.Int as Int
 import Data.Map as Map
 import Data.Set as Set
 import Data.String as String
-import Data.Time.Duration (Days(..))
+import Data.Time.Duration (Days(..), Hours(..))
 import Effect.Class.Console as Console
+import JSON as JSON
 import Node.FS.Aff as FS.Aff
 import Node.Path as Path
 import Node.Process as Process
@@ -62,11 +48,15 @@ import Registry.Manifest (Manifest(..))
 import Registry.ManifestIndex (ManifestIndex)
 import Registry.ManifestIndex as ManifestIndex
 import Registry.Metadata (Metadata(..))
+import Registry.Operation as Operation
 import Registry.PackageName (PackageName)
 import Registry.PackageName as PackageName
 import Registry.PackageSet (PackageSet(..))
 import Registry.Range (Range)
 import Registry.Range as Range
+import Registry.Scripts.PackageSetPlanner as Planner
+import Registry.Scripts.PackageSetUpdater as PackageSetUpdater
+import Registry.Sha256 as Sha256
 import Registry.Version (Version)
 import Registry.Version as Version
 import Run (AFF, EFFECT, Run)
@@ -77,20 +67,23 @@ import Run.Except as Except
 type Options =
   { markdown :: Maybe FilePath
   , output :: Maybe FilePath
-  , verify :: Boolean
+  , submit :: Boolean
   }
 
 parser :: ArgParser Options
 parser = ado
-  verify <- Arg.flag [ "--verify" ] "Atomically compile the planned update without publishing it." # Arg.boolean # Arg.default false
+  -- Kept so the existing workflow remains compatible. Compile verification is
+  -- now intrinsic to planning and is always performed.
+  _ <- Arg.flag [ "--verify" ] "Compatibility flag; compile-guided planning always verifies the result." # Arg.boolean # Arg.default false
+  submit <- Arg.flag [ "--submit" ] "Submit the exact verified automatic plan to the registry API." # Arg.boolean # Arg.default false
   output <- Arg.argument [ "--output" ] "Write the structured report as JSON." # Arg.optional
   markdown <- Arg.argument [ "--markdown" ] "Write the human-readable report as Markdown." # Arg.optional
-  in { markdown, output, verify }
+  in { markdown, output, submit }
 
 main :: Effect Unit
 main = launchAff_ do
   args <- Array.drop 2 <$> liftEffect Process.argv
-  let description = "Report, plan, and optionally verify registry versions pending a package set update."
+  let description = "Compile, plan, and report registry versions pending a package set update."
   options <- case Arg.parseArgs "version-check" description parser args of
     Left err -> Console.log (Arg.printArgError err) *> liftEffect (Process.exit' 1)
     Right parsed -> pure parsed
@@ -114,7 +107,7 @@ main = launchAff_ do
       , cacheRef: registryCacheRef
       }
 
-  runVersionCheck options.verify
+  runVersionCheck options.submit resourceEnv.registryApiUrl
     # PackageSets.interpret (PackageSets.handle { workdir: scratchDir })
     # Except.runExcept
     # Registry.interpretRead (Registry.handleRead registryEnv)
@@ -126,11 +119,21 @@ main = launchAff_ do
       Left err -> do
         Console.error $ "Error: " <> err
         liftEffect $ Process.exit' 1
-      Right report -> do
-        let markdown = renderMarkdown report
+      Right result -> do
+        let markdown = renderMarkdown result.report
         Console.log markdown
-        for_ options.output \path -> writeJsonFile reportCodec path report
+        for_ options.output \path -> writeJsonFile reportCodec path result.report
         for_ options.markdown \path -> FS.Aff.writeTextFile UTF8 path (markdown <> "\n")
+        let
+          fatalError = case result.submissionError of
+            Just error -> Just error
+            Nothing | result.report.verification.status == "infrastructure-failed" ->
+              Just $ fromMaybe "Package set planning failed because of an infrastructure error." result.report.verification.error
+            Nothing | Just error <- result.report.manualAnalysis.error -> Just error
+            Nothing -> Nothing
+        for_ fatalError \error -> do
+          Console.error $ "Error: " <> error
+          liftEffect $ Process.exit' 1
 
 type Incompatibility =
   { dependency :: PackageName
@@ -146,7 +149,7 @@ type PendingPackage =
   { blockedBy :: Array Incompatibility
   , blockers :: Array Incompatibility
   , candidate :: Version
-  , candidateCompilerCompatible :: Boolean
+  , candidateCompilerRecorded :: Boolean
   , candidatePublished :: DateTime
   , current :: Version
   , directDependants :: Int
@@ -157,25 +160,36 @@ type PendingPackage =
   , transitiveDependants :: Int
   }
 
-type Plan =
+type Report =
+  { compiler :: Version
+  , generatedAt :: DateTime
+  , latestRangeMismatches :: Array Incompatibility
+  , manualAnalysis :: ManualAnalysisReport
+  , manualInterventions :: Array ManualInterventionReport
+  , manualInterventionsDeferred :: Boolean
+  , packageSet :: Version
+  , pending :: Array PendingPackage
+  , plan :: PlanReport
+  , verification :: Planner.Verification
+  }
+
+type PlanReport =
   { error :: Maybe String
   , packages :: Map PackageName Version
   , searchTruncated :: Boolean
   }
 
-type Verification =
+type ManualAnalysisReport =
   { error :: Maybe String
-  , status :: String
+  , searchTruncated :: Boolean
   }
 
-type Report =
-  { compiler :: Version
-  , generatedAt :: DateTime
-  , latestIncompatibilities :: Array Incompatibility
-  , packageSet :: Version
-  , pending :: Array PendingPackage
-  , plan :: Plan
-  , verification :: Verification
+type ManualInterventionReport =
+  { component :: String
+  , fingerprint :: String
+  , markdownBody :: String
+  , removal :: { payload :: Operation.PackageSetOperation, verified :: Boolean }
+  , title :: String
   }
 
 incompatibilityCodec :: CJ.Codec Incompatibility
@@ -194,7 +208,7 @@ pendingPackageCodec = CJ.named "VersionCheckPendingPackage" $ CJ.Record.object
   { blockedBy: CJ.array incompatibilityCodec
   , blockers: CJ.array incompatibilityCodec
   , candidate: Version.codec
-  , candidateCompilerCompatible: CJ.boolean
+  , candidateCompilerRecorded: CJ.boolean
   , candidatePublished: Internal.Codec.iso8601DateTime
   , current: Version.codec
   , directDependants: CJ.int
@@ -205,24 +219,45 @@ pendingPackageCodec = CJ.named "VersionCheckPendingPackage" $ CJ.Record.object
   , transitiveDependants: CJ.int
   }
 
-planCodec :: CJ.Codec Plan
-planCodec = CJ.named "VersionCheckPlan" $ CJ.Record.object
+verificationCodec :: CJ.Codec Planner.Verification
+verificationCodec = CJ.named "PackageSetPlannerVerification" $ CJ.Record.object
+  { error: CJ.Common.nullable CJ.string
+  , status: CJ.string
+  }
+
+planCodec :: CJ.Codec PlanReport
+planCodec = CJ.named "PackageSetPlan" $ CJ.Record.object
   { error: CJ.Common.nullable CJ.string
   , packages: Internal.Codec.packageMap Version.codec
   , searchTruncated: CJ.boolean
   }
 
-verificationCodec :: CJ.Codec Verification
-verificationCodec = CJ.named "VersionCheckVerification" $ CJ.Record.object
+manualAnalysisCodec :: CJ.Codec ManualAnalysisReport
+manualAnalysisCodec = CJ.named "PackageSetManualAnalysis" $ CJ.Record.object
   { error: CJ.Common.nullable CJ.string
-  , status: CJ.string
+  , searchTruncated: CJ.boolean
+  }
+
+manualInterventionCodec :: CJ.Codec ManualInterventionReport
+manualInterventionCodec = CJ.named "PackageSetManualIntervention" $ CJ.Record.object
+  { component: CJ.string
+  , fingerprint: CJ.string
+  , markdownBody: CJ.string
+  , removal: CJ.Record.object
+      { payload: Operation.packageSetOperationCodec
+      , verified: CJ.boolean
+      }
+  , title: CJ.string
   }
 
 reportCodec :: CJ.Codec Report
 reportCodec = CJ.named "VersionCheckReport" $ CJ.Record.object
   { compiler: Version.codec
   , generatedAt: Internal.Codec.iso8601DateTime
-  , latestIncompatibilities: CJ.array incompatibilityCodec
+  , latestRangeMismatches: CJ.array incompatibilityCodec
+  , manualAnalysis: manualAnalysisCodec
+  , manualInterventions: CJ.array manualInterventionCodec
+  , manualInterventionsDeferred: CJ.boolean
   , packageSet: Version.codec
   , pending: CJ.array pendingPackageCodec
   , plan: planCodec
@@ -231,275 +266,151 @@ reportCodec = CJ.named "VersionCheckReport" $ CJ.Record.object
 
 type Candidate =
   { candidate :: Version
+  , candidateCompilerRecorded :: Boolean
   , candidatePublished :: DateTime
-  , compatibleVersions :: Array Version
   , current :: Version
   , name :: PackageName
   , staleSince :: DateTime
   }
 
-type Choice =
-  { freshness :: Int
-  , upgrade :: Int
-  , version :: Version
-  }
-
-type PlannerVariable =
-  { choices :: Array Choice
-  , name :: PackageName
-  }
-
-type PlanScore =
-  { freshness :: Int
-  , upgrades :: Int
-  }
-
-type ScoredPlan =
-  { packages :: Map PackageName Version
-  , score :: PlanScore
-  }
+type VersionCheckEffects = (REGISTRY_READ + PACKAGE_SETS + STORAGE + RESOURCE_ENV + LOG + EXCEPT String + AFF + EFFECT + ())
 
-type SearchState =
-  { best :: Maybe ScoredPlan
-  , remainingNodes :: Int
-  , truncated :: Boolean
+type VersionCheckResult =
+  { report :: Report
+  , submissionError :: Maybe String
   }
 
-type VersionCheckEffects = (REGISTRY_READ + PACKAGE_SETS + STORAGE + RESOURCE_ENV + LOG + EXCEPT String + AFF + EFFECT + ())
-
-runVersionCheck :: Boolean -> Run VersionCheckEffects Report
-runVersionCheck verify = do
-  Log.info "Registry Version Check: checking for pending package set updates..."
+runVersionCheck :: Boolean -> URL -> Run VersionCheckEffects VersionCheckResult
+runVersionCheck submit registryApiUrl = do
+  Log.info "Registry Version Check: compile-guided planning for pending package set updates..."
   packageSet <- Registry.readLatestPackageSet >>= case _ of
     Nothing -> Except.throw "No package set found."
     Just found -> pure found
   metadata <- Registry.readAllMetadata
   manifests <- Registry.readAllManifests
   generatedAt <- nowUTC
-  let initial = buildReport generatedAt packageSet metadata manifests
-  verification <- verifyPlan verify packageSet initial.plan
-  let report = initial { verification = verification }
+  let recent = PackageSetUpdater.selectPackageSetCandidates (PackageSetUpdater.RecentUploads generatedAt (Hours 24.0)) packageSet metadata
+  let plannerCandidates = PackageSetUpdater.plannerCandidates packageSet metadata manifests recent
+  planning <- Planner.planPackageSet packageSet manifests plannerCandidates
+  report <- buildReport generatedAt packageSet metadata manifests planning
   Log.info $ "Found " <> show (Array.length report.pending) <> " package versions pending a package set update."
-  pure report
-
-verifyPlan
-  :: forall r
-   . Boolean
-  -> PackageSet
-  -> Plan
-  -> Run (PACKAGE_SETS + LOG + EXCEPT String + AFF + EFFECT + r) Verification
-verifyPlan verify packageSet plan
-  | not verify = pure { error: Nothing, status: "not-run" }
-  | Just error <- plan.error = pure { error: Just error, status: "failed" }
-  | Map.isEmpty plan.packages = pure { error: Nothing, status: "not-needed" }
-  | otherwise = do
-      Log.info $ "Atomically compiling " <> show (Map.size plan.packages) <> " planned package updates..."
-      Except.runExcept (PackageSets.upgradeAtomic packageSet (un PackageSet packageSet).compiler (map PackageSets.Update plan.packages)) >>= case _ of
-        Left error -> pure { error: Just error, status: "failed" }
-        Right (Left error) -> pure { error: Just error, status: "failed" }
-        Right (Right _) -> pure { error: Nothing, status: "verified" }
-
-buildReport :: DateTime -> PackageSet -> Map PackageName Metadata -> ManifestIndex -> Report
-buildReport generatedAt packageSet@(PackageSet set) metadata manifests = do
-  let candidates = findCandidates set.compiler set.packages metadata manifests
+  let
+    shouldSubmit =
+      submit
+        && planning.automatic.verification.status
+        == "verified"
+        && not (Map.isEmpty planning.automatic.packages)
+  submissionResult <-
+    if submit then do
+      Except.runExcept do
+        latest <- Registry.readLatestPackageSet >>= case _ of
+          Nothing -> Except.throw "The latest package set disappeared before submission."
+          Just latestPackageSet -> pure latestPackageSet
+        PackageSetUpdater.submitVerifiedPlan PackageSetUpdater.Submit registryApiUrl packageSet latest planning.automatic
+    else
+      pure $ Right unit
+  let
+    submissionError = either Just (const Nothing) submissionResult
+    finalReport = case submissionResult of
+      Left error -> report
+        { plan = report.plan { error = Just $ "Automatic submission failed: " <> error }
+        , verification = { error: Just error, status: "infrastructure-failed" }
+        }
+      Right _ | shouldSubmit -> report
+        { manualInterventions = []
+        , manualInterventionsDeferred = true
+        }
+      Right _ -> report
+  pure { report: finalReport, submissionError }
+
+buildReport :: forall m. MonadEffect m => DateTime -> PackageSet -> Map PackageName Metadata -> ManifestIndex -> Planner.Plan -> m Report
+buildReport generatedAt (PackageSet set) metadata manifests planning = do
+  let candidates = findCandidates set.compiler set.packages metadata
   let latest = Map.fromFoldable $ candidates <#> \candidate -> Tuple candidate.name candidate.candidate
   let proposed = Map.union latest set.packages
-  let
-    plan = case planPackageSet packageSet metadata manifests of
-      Left error -> { error: Just error, packages: Map.empty, searchTruncated: false }
-      Right { packages, searchTruncated } -> { error: Nothing, packages, searchTruncated }
-  let planned = Map.union plan.packages set.packages
-  let latestIncompatibilities = findIncompatibilities set.packages proposed manifests
+  let planned = Map.union planning.automatic.packages set.packages
+  let latestRangeMismatches = findIncompatibilities set.packages proposed manifests
   let
     pending = candidates <#> \candidate -> do
       let direct = directDependants set.packages manifests candidate.name
       let transitive = transitiveDependants set.packages manifests candidate.name
-      let candidateIncompatibilities = findIncompatibilities set.packages (Map.insert candidate.name candidate.candidate planned) manifests
-      { blockedBy: Array.filter (_.package >>> eq candidate.name) candidateIncompatibilities
-      , blockers: Array.filter (_.dependency >>> eq candidate.name) candidateIncompatibilities
+      let advisory = findIncompatibilities set.packages (Map.insert candidate.name candidate.candidate planned) manifests
+      { blockedBy: Array.filter (_.package >>> eq candidate.name) advisory
+      , blockers: Array.filter (_.dependency >>> eq candidate.name) advisory
       , candidate: candidate.candidate
-      , candidateCompilerCompatible: Array.elem candidate.candidate candidate.compatibleVersions
+      , candidateCompilerRecorded: candidate.candidateCompilerRecorded
       , candidatePublished: candidate.candidatePublished
       , current: candidate.current
       , directDependants: Array.length direct
       , name: candidate.name
-      , planned: Map.lookup candidate.name plan.packages
+      , planned: Map.lookup candidate.name planning.automatic.packages
       , staleDays: daysBetween candidate.staleSince generatedAt
       , staleSince: candidate.staleSince
       , transitiveDependants: Array.length transitive
       }
-  { compiler: set.compiler
-  , generatedAt
-  , latestIncompatibilities
-  , packageSet: set.version
-  , pending
-  , plan
-  , verification: { error: Nothing, status: "not-run" }
-  }
+  let automatic = planning.automatic
+  manualInterventions <- traverse (manualReport set.version set.compiler) planning.manualInterventions
+  pure
+    { compiler: set.compiler
+    , generatedAt
+    , latestRangeMismatches
+    , manualAnalysis: { error: planning.manualError, searchTruncated: planning.manualSearchTruncated }
+    , manualInterventions
+    , manualInterventionsDeferred: false
+    , packageSet: set.version
+    , pending
+    , plan: { error: automatic.verification.error, packages: automatic.packages, searchTruncated: automatic.searchTruncated }
+    , verification: automatic.verification
+    }
 
--- Candidate versions are restricted to releases known to compile with the
--- package set compiler and present in the manifest index. The report still
--- retains the actual latest release so incompatible latest releases stay
--- visible even when the planner chooses an intermediate version.
-findCandidates
-  :: Version
-  -> Map PackageName Version
-  -> Map PackageName Metadata
-  -> ManifestIndex
-  -> Array Candidate
-findCandidates compiler packages metadata manifests = Array.mapMaybe toCandidate (Map.toUnfoldable packages)
+manualReport :: forall m. MonadEffect m => Version -> Version -> Planner.ManualIntervention -> m ManualInterventionReport
+manualReport baseline compiler intervention = do
+  let removals = Map.fromFoldable $ intervention.removals <#> \name -> Tuple name Nothing
+  let update = { compiler: Nothing, packages: Map.union removals (map Just intervention.packages) }
+  let payload = Operation.PackageSetUpdateFrom baseline update
+  let names = Array.sort $ map PackageName.print (Map.keys update.packages # Array.fromFoldable)
+  let
+    decision = String.joinWith "|"
+      [ Version.print compiler
+      , JSON.print (CJ.encode Operation.packageSetOperationCodec payload)
+      , intervention.verification.status
+      , fromMaybe "" intervention.verification.error
+      , fromMaybe "" intervention.compilerError
+      ]
+  decisionHash <- Sha256.print <$> Sha256.hashString decision
+  componentHash <- Sha256.print <$> Sha256.hashString (String.joinWith "|" names)
+  let safeComponentHash = componentHash # String.replaceAll (String.Pattern "+") (String.Replacement "-") # String.replaceAll (String.Pattern "/") (String.Replacement "_") # String.replaceAll (String.Pattern "=") (String.Replacement "")
+  let component = "packages-" <> String.take 72 (String.joinWith "-" names) <> "-" <> String.take 32 safeComponentHash
+  let verified = intervention.verification.status == "verified" && not (Array.null intervention.removals)
+  let title = String.trim $ String.take 256 $ "Package set intervention: " <> String.joinWith ", " names
+  let
+    markdownBody = String.joinWith "\n"
+      [ "The planner tested this component with PureScript `" <> Version.print compiler <> "` against package set `" <> Version.print baseline <> "`."
+      , ""
+      , if verified then "The removal-containing payload is compile-verified, but requires trustee review because it removes packages and their reverse-dependency closure." else "No compile-verified removal is available. The payload and compiler output below are diagnostic only and must not be applied as a verified plan."
+      , maybe "" (\error -> "\nCompiler evidence:\n```text\n" <> printableEvidence error <> "\n```") intervention.compilerError
+      , maybe "" (\error -> "\nPlanner evidence:\n```text\n" <> printableEvidence error <> "\n```") intervention.verification.error
+      ]
+  pure { component, fingerprint: decisionHash, markdownBody, removal: { payload, verified }, title }
+
+-- Compiler history is retained as a diagnostic, but does not gate candidates.
+findCandidates :: Version -> Map PackageName Version -> Map PackageName Metadata -> Array Candidate
+findCandidates compiler packages metadata = Array.mapMaybe toCandidate (Map.toUnfoldable packages)
   where
   toCandidate (Tuple name current) = do
     Metadata packageMetadata <- Map.lookup name metadata
     let newer = Array.filter (fst >>> (_ > current)) (Map.toUnfoldable packageMetadata.published)
     latest@(Tuple candidate candidateMetadata) <- Array.last $ Array.sortBy (comparing fst) newer
     let Tuple _ staleMetadata = Foldable.minimumBy (comparing (_.publishedTime <<< snd)) newer # fromMaybe latest
-    let staleSince = staleMetadata.publishedTime
-    let
-      compatibleVersions = newer
-        # Array.mapMaybe
-            ( \(Tuple version published) -> do
-                guard $ Foldable.elem compiler published.compilers
-                _ <- ManifestIndex.lookup name version manifests
-                pure version
-            )
-        # Array.sort
     pure
       { candidate
+      , candidateCompilerRecorded: Foldable.elem compiler candidateMetadata.compilers
       , candidatePublished: candidateMetadata.publishedTime
-      , compatibleVersions
       , current
       , name
-      , staleSince
+      , staleSince: staleMetadata.publishedTime
       }
 
--- Maximize the number of upgraded packages, then their cumulative freshness,
--- while satisfying the exact selected dependency versions. Existing range
--- mismatches are tolerated only when both ends of that dependency edge remain
--- unchanged; this is necessary because package sets prove compatibility by
--- compilation and some historical manifests have stale bounds.
-planPackageSet
-  :: PackageSet
-  -> Map PackageName Metadata
-  -> ManifestIndex
-  -> Either String { packages :: Map PackageName Version, searchTruncated :: Boolean }
-planPackageSet (PackageSet set) metadata manifests = do
-  let candidates = findCandidates set.compiler set.packages metadata manifests
-  let variables = Array.mapMaybe toVariable candidates
-  let fixed = Foldable.foldl (flip Map.delete) set.packages (map _.name variables)
-  unless (completePlanIsValid manifests set.packages set.packages) do
-    Left "The current package set is missing a manifest or one of its declared dependencies."
-  let search = searchPlan manifests set.packages variables fixed
-  result <- note "No compatible package set update could be planned without introducing new dependency-range violations." search.best
-  pure
-    { packages: Map.filterWithKey
-        (\name version -> maybe false (version > _) (Map.lookup name set.packages))
-        result.packages
-    , searchTruncated: search.truncated
-    }
-  where
-  toVariable candidate = do
-    guard $ not (Array.null candidate.compatibleVersions)
-    let
-      choices =
-        [ { freshness: 0, upgrade: 0, version: candidate.current } ]
-          <> Array.mapWithIndex
-            (\index version -> { freshness: index + 1, upgrade: 1, version })
-            candidate.compatibleVersions
-    pure { choices, name: candidate.name }
-
--- Branch-and-bound visits newest choices first and prunes a branch when its
--- best possible score cannot improve on the best complete plan already found.
--- The node budget keeps a pathological dependency graph from hanging the
--- weekly report; a truncated plan is reported but not automatically submitted.
-searchPlan
-  :: ManifestIndex
-  -> Map PackageName Version
-  -> Array PlannerVariable
-  -> Map PackageName Version
-  -> { best :: Maybe ScoredPlan, truncated :: Boolean }
-searchPlan manifests baseline variables fixed = do
-  let baselinePlan = { packages: baseline, score: { freshness: 0, upgrades: 0 } }
-  let result = go 0 fixed { freshness: 0, upgrades: 0 } { best: Just baselinePlan, remainingNodes: 50_000, truncated: false }
-  { best: result.best, truncated: result.truncated }
-  where
-  go :: Int -> Map PackageName Version -> PlanScore -> SearchState -> SearchState
-  go offset selected score state
-    | state.remainingNodes <= 0 = state { truncated = true }
-    | otherwise = do
-        let nextState = state { remainingNodes = state.remainingNodes - 1 }
-        let remaining = Array.drop offset variables
-        let potential = addScores score (maximumRemainingScore remaining)
-        if maybe false (not <<< betterScore potential <<< _.score) nextState.best then
-          nextState
-        else case Array.index variables offset of
-          Nothing ->
-            if completePlanIsValid manifests baseline selected then nextState { best = chooseBetter { packages: selected, score } nextState.best } else nextState
-          Just variable ->
-            Array.foldl
-              ( \currentState choice -> do
-                  let nextSelected = Map.insert variable.name choice.version selected
-                  let nextRemaining = Array.drop (offset + 1) variables
-                  let nextScore = addScores score { freshness: choice.freshness, upgrades: choice.upgrade }
-                  if partialPlanIsPossible manifests baseline nextSelected nextRemaining then
-                    go (offset + 1) nextSelected nextScore currentState
-                  else
-                    currentState
-              )
-              nextState
-              (Array.reverse variable.choices)
-
-maximumRemainingScore :: Array PlannerVariable -> PlanScore
-maximumRemainingScore = Array.foldl addMaximum { freshness: 0, upgrades: 0 }
-  where
-  addMaximum score variable = case Array.last variable.choices of
-    Nothing -> score
-    Just choice -> addScores score { freshness: choice.freshness, upgrades: choice.upgrade }
-
-addScores :: PlanScore -> PlanScore -> PlanScore
-addScores a b =
-  { freshness: a.freshness + b.freshness
-  , upgrades: a.upgrades + b.upgrades
-  }
-
-betterScore :: PlanScore -> PlanScore -> Boolean
-betterScore a b = a.upgrades > b.upgrades || (a.upgrades == b.upgrades && a.freshness > b.freshness)
-
-chooseBetter :: ScoredPlan -> Maybe ScoredPlan -> Maybe ScoredPlan
-chooseBetter candidate = case _ of
-  Nothing -> Just candidate
-  Just current | betterScore candidate.score current.score -> Just candidate
-  current -> current
-
--- Check selected manifests against exact selected dependency versions. For an
--- unselected dependency, at least one of its remaining choices must satisfy
--- the range (or preserve an unchanged baseline mismatch).
-partialPlanIsPossible :: ManifestIndex -> Map PackageName Version -> Map PackageName Version -> Array PlannerVariable -> Boolean
-partialPlanIsPossible manifests baseline selected remaining = all manifestIsPossible (Map.toUnfoldable selected :: Array (Tuple PackageName Version))
-  where
-  remainingChoices = Map.fromFoldable $ remaining <#> \variable -> Tuple variable.name variable.choices
-
-  manifestIsPossible (Tuple name version) = fromMaybe false do
-    Manifest manifest <- ManifestIndex.lookup name version manifests
-    pure $ all (dependencyIsPossible name version) (Map.toUnfoldable manifest.dependencies :: Array (Tuple PackageName Range))
-
-  dependencyIsPossible name packageVersion (Tuple dependency range) = case Map.lookup dependency selected of
-    Just dependencyVersion -> choiceIsCompatible name packageVersion dependency range dependencyVersion
-    Nothing -> fromMaybe false do
-      choices <- Map.lookup dependency remainingChoices
-      pure $ any (choiceIsCompatible name packageVersion dependency range <<< _.version) choices
-
-  choiceIsCompatible name packageVersion dependency range dependencyVersion =
-    Range.includes range dependencyVersion
-      ||
-        ( Map.lookup name baseline == Just packageVersion
-            && Map.lookup dependency baseline
-            == Just dependencyVersion
-        )
-
-completePlanIsValid :: ManifestIndex -> Map PackageName Version -> Map PackageName Version -> Boolean
-completePlanIsValid manifests baseline selected = partialPlanIsPossible manifests baseline selected []
-
 findIncompatibilities :: Map PackageName Version -> Map PackageName Version -> ManifestIndex -> Array Incompatibility
 findIncompatibilities baseline selected manifests = do
   Tuple package version <- Map.toUnfoldable selected
@@ -540,31 +451,57 @@ daysBetween from to = do
 
 renderMarkdown :: Report -> String
 renderMarkdown report = String.joinWith "\n"
-  [ "# Weekly package set version report"
+  [ "# Daily package set planning report"
   , ""
   , "Package set: `" <> Version.print report.packageSet <> "` (PureScript `" <> Version.print report.compiler <> "`)"
   , "Generated: `" <> Internal.Codec.formatIso8601 report.generatedAt <> "`"
-  , "Verification: **" <> report.verification.status <> "**"
-  , maybe "" (\error -> "\nVerification error:\n```text\n" <> String.take 4_000 error <> "\n```") report.verification.error
+  , "Automatic plan verification: **" <> report.verification.status <> "**"
+  , renderError "Automatic planning error" report.plan.error
+  , ""
+  , "## Verified automatic update"
+  , ""
+  , if Map.isEmpty report.plan.packages then "No automatic package updates were planned."
+    else renderUpdates report.plan.packages
+  , if report.plan.searchTruncated then "\n⚠️ The automatic search exhausted its probe budget. A payload marked verified still compiled exactly and may be published, but it is only the best verified plan found within the budget." else ""
+  , ""
+  , "The automatic lane is upgrade-only: it does not remove packages, downgrade versions, or change the compiler."
+  , ""
+  , "## Manual interventions"
   , ""
-  , "## Planned update"
+  , renderError "Manual-intervention analysis error" report.manualAnalysis.error
+  , if report.manualAnalysis.searchTruncated then "\n⚠️ Manual-intervention analysis exhausted its probe budget. Existing trustee issues are preserved until a complete run can reconcile them." else ""
+  , if report.manualInterventionsDeferred then "Residual trustee decisions were deferred because the automatic plan advanced the package-set baseline. They will be recomputed and compile-verified against the new baseline on the next run."
+    else renderManualInterventions report.manualInterventions
   , ""
-  , if Map.isEmpty report.plan.packages then "No package updates were planned."
-    else String.joinWith "\n" do
-      Tuple name version <- Map.toUnfoldable report.plan.packages
-      [ "- `" <> PackageName.print name <> "@" <> Version.print version <> "`" ]
-  , if report.plan.searchTruncated then "\n⚠️ Planner search limit reached; this is the best compatible plan found so far and will not be submitted automatically." else ""
-  , maybe "" (\error -> "\nPlanner error: " <> error) report.plan.error
+  , "## Advisory range diagnostics"
+  , ""
+  , "Declared dependency ranges are shown for maintainers, but never gate compile-guided candidates."
+  , if Array.null report.latestRangeMismatches then "\nNo range mismatches were found in the all-latest proposal."
+    else "\nThe all-latest proposal has **" <> show (Array.length report.latestRangeMismatches) <> "** declared range mismatches."
   , ""
   , "## Pending versions"
   , ""
   , renderPendingPackages report.pending
   ]
   where
+  renderUpdates packages = String.joinWith "\n" do
+    Tuple name version <- Map.toUnfoldable packages
+    [ "- `" <> PackageName.print name <> "@" <> Version.print version <> "`" ]
+
+  renderManualInterventions interventions
+    | Array.null interventions = "No residual manual-intervention payloads were found."
+    | otherwise = String.joinWith "\n\n" $ Array.mapWithIndex renderManual interventions
+
+  renderManual index intervention = String.joinWith "\n"
+    [ "### " <> intervention.title
+    , ""
+    , "Compile-verified trustee decision issue " <> show (index + 1) <> "; fingerprint `" <> intervention.fingerprint <> "`."
+    ]
+
   renderPendingPackages pending
     | Array.null pending = "No package versions are pending."
     | otherwise = do
-        let visible = Array.take 100 pending
+        let visible = Array.take 25 pending
         let omitted = Array.length pending - Array.length visible
         String.joinWith "\n\n" (map renderPending visible)
           <> if omitted > 0 then "\n\n_" <> show omitted <> " more pending packages are available in the JSON artifact._" else ""
@@ -574,20 +511,34 @@ renderMarkdown report = String.joinWith "\n"
     , ""
     , "- Stale for **" <> show pending.staleDays <> " days** (since `" <> Internal.Codec.formatIso8601 pending.staleSince <> "`)"
     , "- Dependants in the current set: **" <> show pending.directDependants <> " direct**, **" <> show pending.transitiveDependants <> " transitive**"
-    , "- Planned version: " <> maybe "none" (\version -> "`" <> Version.print version <> "`") pending.planned
-    , "- Latest candidate compatible with the set compiler: **" <> if pending.candidateCompilerCompatible then "yes**" else "no**"
-    , renderRelations "Held back by" pending.blockers
-    , renderRelations "Candidate blocked by" pending.blockedBy
+    , "- Verified automatic version: " <> maybe "none" (\version -> "`" <> Version.print version <> "`") pending.planned
+    , "- Current compiler appears in candidate publication metadata: **" <> if pending.candidateCompilerRecorded then "yes** (diagnostic only)" else "no** (diagnostic only)"
+    , renderRelations "Advisory dependant range mismatches" pending.blockers
+    , renderRelations "Advisory dependency range mismatches" pending.blockedBy
     ]
 
   renderRelations label relations
     | Array.null relations = "- " <> label <> ": none"
-    | otherwise = "- " <> label <> ":\n" <> String.joinWith "\n" (map (renderRelation >>> ("  - " <> _)) relations)
+    | otherwise = do
+        let visible = Array.take 5 relations
+        let omitted = Array.length relations - Array.length visible
+        "- " <> label <> ":\n" <> String.joinWith "\n" (map (renderRelation >>> ("  - " <> _)) visible)
+          <> if omitted > 0 then "\n  - _" <> show omitted <> " more in the JSON artifact._" else ""
 
   renderRelation relation = String.joinWith " "
-    [ "`" <> PackageName.print relation.package <> "@" <> Version.print relation.version <> "` requires"
+    [ "`" <> PackageName.print relation.package <> "@" <> Version.print relation.version <> "` declares"
     , "`" <> PackageName.print relation.dependency <> " " <> Range.print relation.range <> "`"
-    , "but the proposed version is"
+    , "while the proposed version is"
     , maybe "missing" (\version -> "`" <> Version.print version <> "`") relation.selectedVersion
     , "(" <> show relation.packageDirectDependants <> " direct, " <> show relation.packageTransitiveDependants <> " transitive dependants)"
     ]
+
+renderError :: String -> Maybe String -> String
+renderError _ Nothing = ""
+renderError label (Just error) = "\n" <> label <> ":\n```text\n" <> printableEvidence error <> "\n```"
+
+printableEvidence :: String -> String
+printableEvidence = String.take 4_000
+  >>> String.replaceAll
+    (String.Pattern "<!-- registry-version-check:")
+    (String.Replacement "&lt;!-- registry-version-check:")
diff --git a/scripts/test/Main.purs b/scripts/test/Main.purs
index 1bf8eba5..0bec8d98 100644
--- a/scripts/test/Main.purs
+++ b/scripts/test/Main.purs
@@ -7,19 +7,25 @@ import Data.Array as Array
 import Data.DateTime (DateTime)
 import Data.Map as Map
 import Data.Set as Set
+import Data.String as String
 import Data.Time.Duration (Hours(..))
+import Registry.App.Effect.PackageSets (Change(..), ChangeSet)
+import Registry.Manifest (Manifest)
 import Registry.ManifestIndex (IncludeRanges(..), ManifestIndex)
 import Registry.ManifestIndex as ManifestIndex
 import Registry.Metadata (Metadata)
 import Registry.Metadata as Metadata
+import Registry.Operation as Operation
 import Registry.PackageName (PackageName)
 import Registry.PackageSet (PackageSet)
 import Registry.PackageSet as PackageSet
+import Registry.Scripts.PackageSetPlanner as Planner
 import Registry.Scripts.PackageSetUpdater as PackageSetUpdater
 import Registry.Scripts.VersionCheck as VersionCheck
 import Registry.Test.Assert as Assert
 import Registry.Test.Utils as Utils
 import Registry.Version (Version)
+import Run as Run
 import Test.Spec as Spec
 import Test.Spec.Reporter.Console (consoleReporter)
 import Test.Spec.Runner.Node (runSpecAndExitProcess)
@@ -27,177 +33,336 @@ import Test.Spec.Runner.Node (runSpecAndExitProcess)
 main :: Effect Unit
 main = runSpecAndExitProcess [ consoleReporter ] do
   Spec.describe "PackageSetUpdater candidate selection" do
-    Spec.it "finds all newer versions of packages already in the package set" do
+    Spec.it "finds newer versions of existing packages without adding old packages" do
       let
         metadata = Map.fromFoldable
           [ Utils.unsafeMetadata "prelude" [ Tuple "1.0.0" [ "0.15.10" ], Tuple "2.0.0" [ "0.15.10" ] ]
           , Utils.unsafeMetadata "effect" [ Tuple "2.0.0" [ "0.15.10" ] ]
-          , Utils.unsafeMetadata "older" [ Tuple "1.0.0" [ "0.15.10" ] ]
           , Utils.unsafeMetadata "never-in-set" [ Tuple "1.0.0" [ "0.15.10" ] ]
           ]
         packageSet = mkPackageSet $ Map.fromFoldable
-          [ Tuple (Utils.unsafePackageName "prelude") (Utils.unsafeVersion "1.0.0")
-          , Tuple (Utils.unsafePackageName "effect") (Utils.unsafeVersion "2.0.0")
-          , Tuple (Utils.unsafePackageName "older") (Utils.unsafeVersion "2.0.0")
+          [ Tuple (name "prelude") (version "1.0.0")
+          , Tuple (name "effect") (version "2.0.0")
           ]
-        expected = Map.singleton (Utils.unsafePackageName "prelude") (Utils.unsafeVersion "2.0.0")
 
       PackageSetUpdater.selectPackageSetCandidates PackageSetUpdater.AllPending packageSet metadata
-        `Assert.shouldEqual` expected
+        `Assert.shouldEqual` Map.singleton (name "prelude") (version "2.0.0")
 
-    Spec.it "preserves recent candidate selection for new packages and upgrades" do
+    Spec.it "preserves recent additions and upgrades" do
       let
         oldTime = Utils.unsafeDateTime "2023-12-30T00:00:00.000Z"
         now = Utils.unsafeDateTime "2024-01-02T00:00:00.000Z"
         metadata = Map.fromFoldable
           [ Utils.unsafeMetadata "prelude" [ Tuple "1.0.0" [ "0.15.10" ], Tuple "2.0.0" [ "0.15.10" ] ]
-          , Utils.unsafeMetadata "effect" [ Tuple "1.0.0" [ "0.15.10" ] ]
           , withPublishedTime oldTime $ Utils.unsafeMetadata "old-upload" [ Tuple "1.0.0" [ "0.15.10" ] ]
           , Utils.unsafeMetadata "new-package" [ Tuple "1.0.0" [ "0.15.10" ] ]
           ]
-        packageSet = mkPackageSet $ Map.fromFoldable
-          [ Tuple (Utils.unsafePackageName "prelude") (Utils.unsafeVersion "1.0.0")
-          , Tuple (Utils.unsafePackageName "effect") (Utils.unsafeVersion "1.0.0")
-          ]
+        packageSet = mkPackageSet $ Map.singleton (name "prelude") (version "1.0.0")
         expected = Map.fromFoldable
-          [ Tuple (Utils.unsafePackageName "prelude") (Utils.unsafeVersion "2.0.0")
-          , Tuple (Utils.unsafePackageName "new-package") (Utils.unsafeVersion "1.0.0")
+          [ Tuple (name "prelude") (version "2.0.0")
+          , Tuple (name "new-package") (version "1.0.0")
           ]
 
       PackageSetUpdater.selectPackageSetCandidates (PackageSetUpdater.RecentUploads now (Hours 24.0)) packageSet metadata
         `Assert.shouldEqual` expected
 
-  Spec.describe "VersionCheck" do
-    Spec.it "plans coordinated updates, falls back to a compatible intermediate version, and reports blockers" do
-      let fixtures = versionCheckFixtures
-      let generatedAt = Utils.unsafeDateTime "2024-01-10T00:00:00.000Z"
-      let report = VersionCheck.buildReport generatedAt fixtures.packageSet fixtures.metadata fixtures.manifests
+    Spec.it "filters stale and already-applied plan entries" do
       let
-        expectedPlan = Map.fromFoldable
-          [ Tuple (Utils.unsafePackageName "alpha") (Utils.unsafeVersion "2.0.0")
-          , Tuple (Utils.unsafePackageName "beta") (Utils.unsafeVersion "2.0.0")
-          , Tuple (Utils.unsafePackageName "gamma") (Utils.unsafeVersion "1.5.0")
+        packageSet = mkPackageSet $ Map.fromFoldable
+          [ Tuple (name "applied") (version "2.0.0")
+          , Tuple (name "stale") (version "3.0.0")
+          , Tuple (name "upgrade") (version "1.0.0")
+          ]
+        planned = Map.fromFoldable
+          [ Tuple (name "applied") (version "2.0.0")
+          , Tuple (name "stale") (version "2.0.0")
+          , Tuple (name "upgrade") (version "2.0.0")
+          , Tuple (name "addition") (version "1.0.0")
+          ]
+        expected = Map.fromFoldable
+          [ Tuple (name "upgrade") (version "2.0.0")
+          , Tuple (name "addition") (version "1.0.0")
           ]
 
-      report.plan.error `Assert.shouldEqual` Nothing
-      report.plan.packages `Assert.shouldEqual` expectedPlan
-      report.plan.searchTruncated `Assert.shouldEqual` false
-
-      let gamma = Utils.fromJust "Missing gamma report." $ Array.find (_.name >>> eq (Utils.unsafePackageName "gamma")) report.pending
-      gamma.candidate `Assert.shouldEqual` Utils.unsafeVersion "2.0.0"
-      gamma.planned `Assert.shouldEqual` Just (Utils.unsafeVersion "1.5.0")
-      gamma.staleSince `Assert.shouldEqual` Utils.unsafeDateTime "2023-12-01T00:00:00.000Z"
-      gamma.staleDays `Assert.shouldEqual` 40
-      gamma.directDependants `Assert.shouldEqual` 2
-      gamma.transitiveDependants `Assert.shouldEqual` 3
-      map _.package gamma.blockers `Assert.shouldEqual` [ Utils.unsafePackageName "consumer", Utils.unsafePackageName "delta" ]
-      gamma.blockedBy `Assert.shouldEqual` []
+      PackageSetUpdater.filterApplicableUpgrades packageSet planned `Assert.shouldEqual` expected
 
-      let consumer = Utils.fromJust "Missing consumer report." $ Array.find (_.name >>> eq (Utils.unsafePackageName "consumer")) report.pending
-      map _.dependency consumer.blockedBy `Assert.shouldEqual` [ Utils.unsafePackageName "gamma" ]
+    Spec.it "uses all newer existing versions and closes recent additions by dependency name" do
+      let
+        packageSet = mkPackageSet $ Map.singleton (name "existing") (version "1.0.0")
+        metadata = Map.fromFoldable
+          [ Utils.unsafeMetadata "existing" [ Tuple "1.0.0" [ "0.1.0" ], Tuple "2.0.0" [ "0.1.0" ], Tuple "3.0.0" [ "0.1.0" ] ]
+          , Utils.unsafeMetadata "recent" [ Tuple "1.0.0" [ "0.1.0" ] ]
+          , Utils.unsafeMetadata "closure-dep" [ Tuple "1.0.0" [ "0.1.0" ], Tuple "2.0.0" [ "0.1.0" ] ]
+          , Utils.unsafeMetadata "upgrade-dep" [ Tuple "1.0.0" [ "0.1.0" ] ]
+          ]
+        manifests = manifestIndex
+          [ Utils.unsafeManifest "existing" "2.0.0" []
+          , Utils.unsafeManifest "existing" "3.0.0" [ Tuple "upgrade-dep" ">=99.0.0 <100.0.0" ]
+          , Utils.unsafeManifest "recent" "1.0.0" [ Tuple "closure-dep" ">=99.0.0 <100.0.0" ]
+          , Utils.unsafeManifest "closure-dep" "2.0.0" []
+          , Utils.unsafeManifest "upgrade-dep" "1.0.0" []
+          ]
+        recent = Map.singleton (name "recent") (version "1.0.0")
+        candidates = PackageSetUpdater.plannerCandidates packageSet metadata manifests recent
+        byName = Map.fromFoldable $ candidates <#> \candidate -> Tuple candidate.name candidate.versions
 
-      case parseJson VersionCheck.reportCodec (printJson VersionCheck.reportCodec report) of
-        Left error -> Assert.fail $ CJ.DecodeError.print error
-        Right decoded -> decoded `Assert.shouldEqual` report
+      Map.lookup (name "existing") byName `Assert.shouldEqual` Just [ version "3.0.0", version "2.0.0" ]
+      Map.lookup (name "recent") byName `Assert.shouldEqual` Just [ version "1.0.0" ]
+      Map.lookup (name "closure-dep") byName `Assert.shouldEqual` Just [ version "2.0.0" ]
+      Map.lookup (name "upgrade-dep") byName `Assert.shouldEqual` Just [ version "1.0.0" ]
 
-    Spec.it "uses the latest version when equally-sized plans are available" do
-      let fixtures = versionCheckFixtures
-      let planned = VersionCheck.planPackageSet fixtures.packageSet fixtures.metadata fixtures.manifests
-      planned `Assert.shouldEqual` Right
-        { packages: Map.fromFoldable
-            [ Tuple (Utils.unsafePackageName "alpha") (Utils.unsafeVersion "2.0.0")
-            , Tuple (Utils.unsafePackageName "beta") (Utils.unsafeVersion "2.0.0")
-            , Tuple (Utils.unsafePackageName "gamma") (Utils.unsafeVersion "1.5.0")
+  Spec.describe "compile-guided package set planner" do
+    Spec.it "keeps every newer existing-package version without compiler-history gating" do
+      let
+        packageSet = mkPackageSet $ Map.singleton (name "example") (version "1.0.0")
+        metadata = Map.singleton (name "example") $ snd $
+          Utils.unsafeMetadata "example"
+            [ Tuple "1.0.0" [ "0.15.10" ]
+            , Tuple "2.0.0" [ "0.14.0" ]
+            , Tuple "3.0.0" [ "0.13.0" ]
             ]
-        , searchTruncated: false
-        }
+        candidates = Planner.existingPackageCandidates packageSet metadata
+
+      map _.versions candidates `Assert.shouldEqual` [ [ version "3.0.0", version "2.0.0" ] ]
 
-    Spec.it "preserves existing range drift without allowing an update to introduce it" do
+    Spec.it "treats declared ranges as advisory when the exact set compiles" do
       let
         packageSet = mkPackageSet $ Map.fromFoldable
-          [ Tuple (Utils.unsafePackageName "dependency") (Utils.unsafeVersion "1.0.0")
-          , Tuple (Utils.unsafePackageName "independent") (Utils.unsafeVersion "1.0.0")
-          , Tuple (Utils.unsafePackageName "legacy") (Utils.unsafeVersion "1.0.0")
-          ]
-        metadata = Map.fromFoldable
-          [ Utils.unsafeMetadata "dependency" [ Tuple "1.0.0" [ "0.15.10" ], Tuple "3.0.0" [ "0.15.10" ] ]
-          , Utils.unsafeMetadata "independent" [ Tuple "1.0.0" [ "0.15.10" ], Tuple "2.0.0" [ "0.15.10" ] ]
-          , Utils.unsafeMetadata "legacy" [ Tuple "1.0.0" [ "0.15.10" ] ]
+          [ Tuple (name "dependency") (version "1.0.0")
+          , Tuple (name "legacy") (version "1.0.0")
           ]
-        manifestSet = Set.fromFoldable
+        manifests = manifestIndex
           [ Utils.unsafeManifest "dependency" "1.0.0" []
-          , Utils.unsafeManifest "dependency" "3.0.0" []
-          , Utils.unsafeManifest "independent" "1.0.0" []
-          , Utils.unsafeManifest "independent" "2.0.0" []
-          , Utils.unsafeManifest "legacy" "1.0.0" [ Tuple "dependency" ">=2.0.0 <3.0.0" ]
+          , Utils.unsafeManifest "dependency" "2.0.0" []
+          , Utils.unsafeManifest "legacy" "1.0.0" [ Tuple "dependency" ">=3.0.0 <4.0.0" ]
           ]
-        manifests = Utils.fromRight "Could not build range-drift manifest index." $ ManifestIndex.fromSet IgnoreRanges manifestSet
+        candidates =
+          [ { current: Just (version "1.0.0"), name: name "dependency", versions: [ version "2.0.0" ] } ]
+        plan = Run.extract $ Planner.planPackageSetWith (\_ _ -> pure Planner.Compiles) packageSet manifests candidates
 
-      VersionCheck.planPackageSet packageSet metadata manifests
-        `Assert.shouldEqual` Right
-          { packages: Map.singleton (Utils.unsafePackageName "independent") (Utils.unsafeVersion "2.0.0")
-          , searchTruncated: false
-          }
+      plan.automatic.packages `Assert.shouldEqual` Map.singleton (name "dependency") (version "2.0.0")
+      plan.automatic.verification.status `Assert.shouldEqual` "verified"
 
-mkPackageSet :: Map PackageName Version -> PackageSet
-mkPackageSet packages = PackageSet.PackageSet
-  { version: Utils.unsafeVersion "1.0.0"
-  , compiler: Utils.unsafeVersion "0.15.10"
-  , published: Utils.unsafeDate "2024-01-01"
-  , packages
-  }
+    Spec.it "does not turn infrastructure failures into compatibility results" do
+      let
+        packageSet = mkPackageSet $ Map.singleton (name "example") (version "1.0.0")
+        manifests = manifestIndex
+          [ Utils.unsafeManifest "example" "1.0.0" []
+          , Utils.unsafeManifest "example" "2.0.0" []
+          ]
+        candidates =
+          [ { current: Just (version "1.0.0"), name: name "example", versions: [ version "2.0.0" ] } ]
+        plan = Run.extract $ Planner.planPackageSetWith (\_ _ -> pure $ Planner.InfrastructureFailure "storage unavailable") packageSet manifests candidates
 
-withPublishedTime :: forall a. DateTime -> Tuple a Metadata -> Tuple a Metadata
-withPublishedTime publishedTime (Tuple name (Metadata.Metadata metadata)) =
-  Tuple name $ Metadata.Metadata $ metadata
-    { published = map (_ { publishedTime = publishedTime }) metadata.published }
+      plan.automatic.packages `Assert.shouldEqual` Map.empty
+      plan.automatic.verification `Assert.shouldEqual`
+        { error: Just "storage unavailable", status: "infrastructure-failed" }
+      plan.manualInterventions `Assert.shouldEqual` []
+
+    Spec.it "reports residual compiler failures even when no removal can be inferred" do
+      let
+        packageSet = mkPackageSet $ Map.singleton (name "example") (version "1.0.0")
+        manifests = manifestIndex
+          [ Utils.unsafeManifest "example" "1.0.0" []
+          , Utils.unsafeManifest "example" "2.0.0" []
+          ]
+        candidates =
+          [ { current: Just (version "1.0.0"), name: name "example", versions: [ version "2.0.0" ] } ]
+        compilerError = "File: scratch/package-sets/packages/example@2.0.0/src/Example.purs\nUnknown value"
+        plan = Run.extract $ Planner.planPackageSetWith (\_ _ -> pure $ Planner.CompilationFailure compilerError) packageSet manifests candidates
+        intervention = Utils.fromJust "Missing unresolved manual intervention." $ Array.head plan.manualInterventions
+
+      intervention.packages `Assert.shouldEqual` Map.singleton (name "example") (version "2.0.0")
+      intervention.removals `Assert.shouldEqual` []
+      intervention.verification.status `Assert.shouldEqual` "unresolved"
+      intervention.compilerError `Assert.shouldEqual` Just compilerError
+
+    Spec.it "rejects compile-successful selections with missing dependency names" do
+      let
+        packageSet = mkPackageSet $ Map.singleton (name "parent") (version "1.0.0")
+        manifests = manifestIndex
+          [ Utils.unsafeManifest "parent" "1.0.0" []
+          , Utils.unsafeManifest "parent" "2.0.0" [ Tuple "new-dependency" ">=99.0.0 <100.0.0" ]
+          , Utils.unsafeManifest "new-dependency" "1.0.0" []
+          ]
+        candidates =
+          [ { current: Just (version "1.0.0"), name: name "parent", versions: [ version "2.0.0" ] }
+          , { current: Nothing, name: name "new-dependency", versions: [ version "1.0.0" ] }
+          ]
+        probe _ changes = pure $ if Map.member (name "new-dependency") changes then Planner.CompilationFailure "dependency does not compile" else Planner.Compiles
+        plan = Run.extract $ Planner.planPackageSetWith probe packageSet manifests candidates
+
+      Map.lookup (name "parent") plan.automatic.packages `Assert.shouldEqual` Nothing
+      (plan.automatic.verification.status == "verified") `Assert.shouldEqual` false
 
-type VersionCheckFixtures =
-  { manifests :: ManifestIndex
+    Spec.it "marks a budget-truncated search incomplete and not submission-ready" do
+      let
+        packageSet = mkPackageSet $ Map.singleton (name "example") (version "1.0.0")
+        manifests = manifestIndex
+          [ Utils.unsafeManifest "example" "1.0.0" []
+          , Utils.unsafeManifest "example" "2.0.0" []
+          ]
+        candidates =
+          [ { current: Just (version "1.0.0"), name: name "example", versions: map (version <<< (_ <> ".0.0") <<< show) (Array.range 2 20) } ]
+        result = Run.extract $ Planner.planAutomaticWith (\_ _ -> pure $ Planner.CompilationFailure "does not compile") packageSet manifests candidates
+
+      result.automatic.searchTruncated `Assert.shouldEqual` true
+      result.automatic.verification.status `Assert.shouldEqual` "incomplete"
+      isJust result.automatic.verification.error `Assert.shouldEqual` true
+
+    Spec.it "keeps an exact verified aggregate when another component search is truncated" do
+      let
+        packageSet = mkPackageSet $ Map.fromFoldable
+          [ Tuple (name "hard") (version "1.0.0")
+          , Tuple (name "workable") (version "1.0.0")
+          ]
+        manifests = manifestIndex
+          [ Utils.unsafeManifest "hard" "1.0.0" []
+          , Utils.unsafeManifest "workable" "1.0.0" []
+          , Utils.unsafeManifest "workable" "2.0.0" []
+          ]
+        candidates =
+          [ { current: Just (version "1.0.0"), name: name "hard", versions: map (version <<< (_ <> ".0.0") <<< show) (Array.range 2 20) }
+          , { current: Just (version "1.0.0"), name: name "workable", versions: [ version "2.0.0" ] }
+          ]
+        probe _ changes = pure $ if Map.member (name "hard") changes then Planner.CompilationFailure "hard fails" else Planner.Compiles
+        result = Run.extract $ Planner.planAutomaticWith probe packageSet manifests candidates
+
+      result.automatic.searchTruncated `Assert.shouldEqual` true
+      result.automatic.verification `Assert.shouldEqual` { error: Nothing, status: "verified" }
+      result.automatic.packages `Assert.shouldEqual` Map.singleton (name "workable") (version "2.0.0")
+
+    Spec.it "finds the set-79 Elmish intermediate and verifies the exact removal closure" do
+      let fixture = elmishFixture
+      let plan = Run.extract $ Planner.planPackageSetWith elmishOracle fixture.packageSet fixture.manifests fixture.candidates
+      let intervention = Utils.fromJust "Missing Elmish manual intervention." $ Array.head plan.manualInterventions
+
+      plan.automatic.verification.status `Assert.shouldEqual` "verified"
+      plan.automatic.packages `Assert.shouldEqual` Map.singleton (name "elmish-html") (version "0.11.1")
+      intervention.packages `Assert.shouldEqual` Map.fromFoldable
+        [ Tuple (name "elmish") (version "0.14.0")
+        , Tuple (name "elmish-html") (version "0.12.0")
+        ]
+      intervention.removals `Assert.shouldEqual`
+        [ name "elmish-hooks", name "elmish-time-machine" ]
+      intervention.verification.status `Assert.shouldEqual` "verified"
+      String.contains (String.Pattern "elmish-hooks@0.11.0/src") (fromMaybe "" intervention.compilerError)
+        `Assert.shouldEqual` true
+      any (flip Array.elem intervention.removals)
+        [ name "elmish-enzyme", name "elmish-testing-library", name "whine-core" ]
+        `Assert.shouldEqual` false
+
+      let generatedAt = Utils.unsafeDateTime "2026-07-27T12:00:00.000Z"
+      report <- VersionCheck.buildReport generatedAt fixture.packageSet fixture.metadata fixture.manifests plan
+      case parseJson VersionCheck.reportCodec (printJson VersionCheck.reportCodec report) of
+        Left error -> Assert.fail $ CJ.DecodeError.print error
+        Right decoded -> decoded `Assert.shouldEqual` report
+      let reportIntervention = Utils.fromJust "Missing report intervention." $ Array.head report.manualInterventions
+      let removalPayload = Operation.packageSetUpdateData reportIntervention.removal.payload
+      Operation.packageSetUpdateExpectedBaseline reportIntervention.removal.payload `Assert.shouldEqual` Just (version "79.0.0")
+      Map.lookup (name "elmish-hooks") removalPayload.packages `Assert.shouldEqual` Just Nothing
+      Map.lookup (name "elmish-time-machine") removalPayload.packages `Assert.shouldEqual` Just Nothing
+      reportIntervention.removal.verified `Assert.shouldEqual` true
+      String.contains (String.Pattern "Advisory range diagnostics") (VersionCheck.renderMarkdown report)
+        `Assert.shouldEqual` true
+
+type ElmishFixture =
+  { candidates :: Array Planner.Candidate
+  , manifests :: ManifestIndex
   , metadata :: Map PackageName Metadata
   , packageSet :: PackageSet
   }
 
-versionCheckFixtures :: VersionCheckFixtures
-versionCheckFixtures = do
+elmishFixture :: ElmishFixture
+elmishFixture = do
   let
-    packageSet = mkPackageSet $ Map.fromFoldable
-      [ Tuple (Utils.unsafePackageName "alpha") (Utils.unsafeVersion "1.0.0")
-      , Tuple (Utils.unsafePackageName "beta") (Utils.unsafeVersion "1.0.0")
-      , Tuple (Utils.unsafePackageName "consumer") (Utils.unsafeVersion "1.0.0")
-      , Tuple (Utils.unsafePackageName "delta") (Utils.unsafeVersion "1.0.0")
-      , Tuple (Utils.unsafePackageName "epsilon") (Utils.unsafeVersion "1.0.0")
-      , Tuple (Utils.unsafePackageName "gamma") (Utils.unsafeVersion "1.0.0")
+    packages = Map.fromFoldable
+      [ Tuple (name "elmish") (version "0.13.0")
+      , Tuple (name "elmish-enzyme") (version "0.1.1")
+      , Tuple (name "elmish-hooks") (version "0.11.0")
+      , Tuple (name "elmish-html") (version "0.10.0")
+      , Tuple (name "elmish-testing-library") (version "0.3.2")
+      , Tuple (name "elmish-time-machine") (version "0.4.2")
+      , Tuple (name "whine-core") (version "0.0.34")
       ]
+    packageSet = PackageSet.PackageSet
+      { version: version "79.0.0"
+      , compiler: version "0.15.15"
+      , published: Utils.unsafeDate "2026-07-27"
+      , packages
+      }
     metadata = Map.fromFoldable
-      [ Utils.unsafeMetadata "alpha" [ Tuple "1.0.0" [ "0.15.10" ], Tuple "2.0.0" [ "0.15.10" ] ]
-      , Utils.unsafeMetadata "beta" [ Tuple "1.0.0" [ "0.15.10" ], Tuple "2.0.0" [ "0.15.10" ] ]
-      , Utils.unsafeMetadata "consumer" [ Tuple "1.0.0" [ "0.15.10" ], Tuple "2.0.0" [ "0.15.10" ] ]
-      , Utils.unsafeMetadata "delta" [ Tuple "1.0.0" [ "0.15.10" ] ]
-      , Utils.unsafeMetadata "epsilon" [ Tuple "1.0.0" [ "0.15.10" ] ]
-      , Utils.unsafeMetadata "gamma" [ Tuple "1.0.0" [ "0.15.10" ], Tuple "1.5.0" [ "0.15.10" ], Tuple "2.0.0" [ "0.15.10" ] ]
-          # withVersionPublishedTime "1.5.0" "2023-12-01T00:00:00.000Z"
-          # withVersionPublishedTime "2.0.0" "2024-01-05T00:00:00.000Z"
+      [ Utils.unsafeMetadata "elmish" [ Tuple "0.13.0" [ "0.15.15" ], Tuple "0.14.0" [ "0.14.0" ] ]
+      , Utils.unsafeMetadata "elmish-html" [ Tuple "0.10.0" [ "0.15.15" ], Tuple "0.11.1" [ "0.15.15" ], Tuple "0.12.0" [ "0.15.15" ] ]
+      , Utils.unsafeMetadata "elmish-hooks" [ Tuple "0.11.0" [ "0.15.15" ] ]
+      , Utils.unsafeMetadata "elmish-time-machine" [ Tuple "0.4.2" [ "0.15.15" ] ]
+      , Utils.unsafeMetadata "elmish-enzyme" [ Tuple "0.1.1" [ "0.15.15" ] ]
+      , Utils.unsafeMetadata "elmish-testing-library" [ Tuple "0.3.2" [ "0.15.15" ] ]
+      , Utils.unsafeMetadata "whine-core" [ Tuple "0.0.34" [ "0.15.15" ] ]
+      ]
+    manifests = manifestIndex
+      [ Utils.unsafeManifest "elmish" "0.13.0" []
+      , Utils.unsafeManifest "elmish" "0.14.0" []
+      , Utils.unsafeManifest "elmish-html" "0.10.0" [ Tuple "elmish" ">=0.10.0 <0.14.0" ]
+      , Utils.unsafeManifest "elmish-html" "0.11.1" [ Tuple "elmish" ">=0.13.0 <0.14.0" ]
+      , Utils.unsafeManifest "elmish-html" "0.12.0" [ Tuple "elmish" ">=0.14.0 <0.15.0" ]
+      , Utils.unsafeManifest "elmish-hooks" "0.11.0" [ Tuple "elmish" ">=0.13.0 <0.14.0" ]
+      , Utils.unsafeManifest "elmish-time-machine" "0.4.2"
+          [ Tuple "elmish" ">=0.13.0 <0.14.0"
+          , Tuple "elmish-hooks" ">=0.11.0 <0.12.0"
+          , Tuple "elmish-html" ">=0.9.0 <0.11.0"
+          ]
+      , Utils.unsafeManifest "elmish-enzyme" "0.1.1" [ Tuple "elmish" ">=0.8.0 <0.14.0" ]
+      , Utils.unsafeManifest "elmish-testing-library" "0.3.2" [ Tuple "elmish" ">=0.8.0 <0.14.0" ]
+      , Utils.unsafeManifest "whine-core" "0.0.34" []
       ]
-    manifestSet = Set.fromFoldable
-      [ Utils.unsafeManifest "alpha" "1.0.0" [ Tuple "beta" ">=1.0.0 <2.0.0" ]
-      , Utils.unsafeManifest "alpha" "2.0.0" [ Tuple "beta" ">=2.0.0 <3.0.0" ]
-      , Utils.unsafeManifest "beta" "1.0.0" []
-      , Utils.unsafeManifest "beta" "2.0.0" []
-      , Utils.unsafeManifest "consumer" "1.0.0" [ Tuple "gamma" ">=1.0.0 <2.0.0" ]
-      , Utils.unsafeManifest "consumer" "2.0.0" [ Tuple "gamma" ">=2.0.0 <3.0.0" ]
-      , Utils.unsafeManifest "delta" "1.0.0" [ Tuple "gamma" ">=1.0.0 <2.0.0" ]
-      , Utils.unsafeManifest "epsilon" "1.0.0" [ Tuple "delta" ">=1.0.0 <2.0.0" ]
-      , Utils.unsafeManifest "gamma" "1.0.0" []
-      , Utils.unsafeManifest "gamma" "1.5.0" []
-      , Utils.unsafeManifest "gamma" "2.0.0" []
+    candidates =
+      [ { current: Just (version "0.13.0"), name: name "elmish", versions: [ version "0.14.0" ] }
+      , { current: Just (version "0.10.0"), name: name "elmish-html", versions: [ version "0.12.0", version "0.11.1" ] }
       ]
-    manifests = Utils.fromRight "Could not build version-check manifest index." $ ManifestIndex.fromSet IgnoreRanges manifestSet
-  { manifests, metadata, packageSet }
-
-withVersionPublishedTime :: forall a. String -> String -> Tuple a Metadata -> Tuple a Metadata
-withVersionPublishedTime version publishedTime (Tuple name (Metadata.Metadata metadata)) = do
-  let parsedVersion = Utils.unsafeVersion version
-  let parsedTime = Utils.unsafeDateTime publishedTime
-  Tuple name $ Metadata.Metadata $ metadata
-    { published = Map.update (Just <<< (_ { publishedTime = parsedTime })) parsedVersion metadata.published }
+  { candidates, manifests, metadata, packageSet }
+
+elmishOracle :: PackageSet -> ChangeSet -> Run.Run () Planner.ProbeResult
+elmishOracle _ changes = do
+  let removed package = Map.lookup (name package) changes == Just Remove
+  let updatedTo package selected = Map.lookup (name package) changes == Just (Update (version selected))
+  let
+    hooksError = String.joinWith "\n"
+      [ "Error 1 of 1"
+      , "  Module: Elmish.Hooks"
+      , "  File: scratch/package-sets/packages/elmish-hooks@0.11.0/src/Elmish/Hooks.purs"
+      , "  Message: Unknown value fork"
+      ]
+  let
+    htmlError = String.joinWith "\n"
+      [ "Error 1 of 1"
+      , "  Module: Elmish.HTML"
+      , "  File: scratch/package-sets/packages/elmish-html@0.12.0/src/Elmish/HTML.purs"
+      ]
+  if removed "elmish-hooks" && removed "elmish-time-machine" then pure Planner.Compiles
+  else if updatedTo "elmish" "0.14.0" then pure $ Planner.CompilationFailure hooksError
+  else if updatedTo "elmish-html" "0.12.0" then pure $ Planner.CompilationFailure htmlError
+  else pure Planner.Compiles
+
+manifestIndex :: Array Manifest -> ManifestIndex
+manifestIndex manifests = Utils.fromRight "Could not build scripts test manifest index." $
+  ManifestIndex.fromSet IgnoreRanges (Set.fromFoldable manifests)
+
+mkPackageSet :: Map PackageName Version -> PackageSet
+mkPackageSet packages = PackageSet.PackageSet
+  { version: version "1.0.0"
+  , compiler: version "0.15.10"
+  , published: Utils.unsafeDate "2024-01-01"
+  , packages
+  }
+
+withPublishedTime :: forall a. DateTime -> Tuple a Metadata -> Tuple a Metadata
+withPublishedTime publishedTime (Tuple package (Metadata.Metadata metadata)) =
+  Tuple package $ Metadata.Metadata $ metadata
+    { published = map (_ { publishedTime = publishedTime }) metadata.published }
+
+name :: String -> PackageName
+name = Utils.unsafePackageName
+
+version :: String -> Version
+version = Utils.unsafeVersion
diff --git a/spago.lock b/spago.lock
index 98749509..53d0e247 100644
--- a/spago.lock
+++ b/spago.lock
@@ -277,6 +277,7 @@
             "fetch",
             "foldable-traversable",
             "formatters",
+            "integers",
             "json",
             "node-fs",
             "node-path",

From 8a24c0dd9f67b62f26ad77e2b0b7d17e0008ae5b Mon Sep 17 00:00:00 2001
From: Thomas Honeyman <hello@thomashoneyman.com>
Date: Tue, 28 Jul 2026 03:04:56 +0000
Subject: [PATCH 7/8] Move version check reconciliation into script

---
 .github/workflows/version-check.yml  | 194 +--------------------
 foreign/src/Foreign/Octokit.purs     |  66 +++++++
 scripts/src/PackageSetPlanner.purs   |  88 ++++++++--
 scripts/src/VersionCheck.purs        |  42 ++++-
 scripts/src/VersionCheck/GitHub.purs | 249 +++++++++++++++++++++++++++
 scripts/test/Main.purs               | 127 ++++++++++++++
 6 files changed, 551 insertions(+), 215 deletions(-)
 create mode 100644 scripts/src/VersionCheck/GitHub.purs

diff --git a/.github/workflows/version-check.yml b/.github/workflows/version-check.yml
index 6d54692b..13251fcc 100644
--- a/.github/workflows/version-check.yml
+++ b/.github/workflows/version-check.yml
@@ -34,7 +34,9 @@ jobs:
           use-flakehub: false
 
       - name: Plan, verify, and submit pending package set updates
-        run: nix run .#version-check -- --verify --submit --output version-check.json --markdown version-check.md
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: nix run .#version-check -- --verify --submit --reconcile-issues --output version-check.json --markdown version-check.md
 
       - name: Upload report
         if: ${{ !cancelled() }}
@@ -46,193 +48,3 @@ jobs:
             version-check.md
           if-no-files-found: warn
           retention-days: 14
-
-      - name: Reconcile rolling report and trustee decisions
-        if: ${{ !cancelled() }}
-        uses: actions/github-script@v8
-        with:
-          github-token: ${{ github.token }}
-          script: |
-            const fs = require("node:fs");
-
-            const expectedRepository = "purescript/registry-dev";
-            const repository = `${context.repo.owner}/${context.repo.repo}`;
-            if (repository !== expectedRepository) {
-              throw new Error(`Refusing to manage issues in ${repository}; expected ${expectedRepository}.`);
-            }
-
-            const summaryMarker = "<!-- registry-version-check:summary:v1 -->";
-            const decisionMarker = "<!-- registry-version-check:decision:v1 -->";
-            const componentMarkerPrefix = "<!-- registry-version-check:component:";
-            const fingerprintMarkerPrefix = "<!-- registry-version-check:fingerprint:";
-            const markerSuffix = " -->";
-            const summaryTitle = "Package set planning report";
-
-            const fail = message => { throw new Error(message); };
-            const isObject = value => value !== null && typeof value === "object" && !Array.isArray(value);
-            const normalize = value => (value || "").replace(/\r\n/g, "\n");
-            const lines = value => normalize(value).split("\n");
-            const hasExactMarker = (issue, marker) => lines(issue.body).includes(marker);
-            const markerFor = (prefix, value) => `${prefix}${value}${markerSuffix}`;
-            const hasReservedMarker = value => lines(value).some(line => line.startsWith("<!-- registry-version-check:"));
-
-            let report;
-            try {
-              report = JSON.parse(fs.readFileSync("version-check.json", "utf8"));
-            } catch (error) {
-              fail(`Could not read the structured version-check report: ${error.message}`);
-            }
-            const markdown = normalize(fs.readFileSync("version-check.md", "utf8")).trimEnd();
-            if (!isObject(report)) fail("The version-check report must be a JSON object.");
-            if (typeof report.manualInterventionsDeferred !== "boolean") fail("The version-check report is missing manualInterventionsDeferred.");
-            if (!isObject(report.manualAnalysis) || typeof report.manualAnalysis.searchTruncated !== "boolean") {
-              fail("The version-check report is missing manualAnalysis state.");
-            }
-            if (markdown.length === 0) fail("The generated Markdown report is empty.");
-            if (hasReservedMarker(markdown)) fail("The generated Markdown contains a reserved automation marker.");
-            const summaryBody = `${summaryMarker}\n\n${markdown}\n`;
-            if (summaryBody.length > 65536) fail("The rolling report issue body is larger than 65536 characters.");
-
-            const allItems = await github.paginate(github.rest.issues.listForRepo, {
-              owner: context.repo.owner, repo: context.repo.repo, state: "all", per_page: 100,
-            });
-            const allIssues = allItems.filter(item => !item.pull_request);
-            const summaryIssues = allIssues.filter(issue => hasExactMarker(issue, summaryMarker));
-            if (summaryIssues.length > 1) fail(`Found ${summaryIssues.length} rolling issues with the exact summary marker.`);
-            if (summaryIssues.some(issue => lines(issue.body).filter(line => line === summaryMarker).length !== 1)) {
-              fail("The rolling issue has duplicate summary markers.");
-            }
-            if (summaryIssues.some(issue => hasExactMarker(issue, decisionMarker))) fail("An issue contains both summary and decision markers.");
-
-            const summary = summaryIssues[0];
-            if (!summary) {
-              await github.rest.issues.create({ owner: context.repo.owner, repo: context.repo.repo, title: summaryTitle, body: summaryBody });
-            } else if (summary.state !== "open" || summary.title !== summaryTitle || normalize(summary.body) !== summaryBody) {
-              await github.rest.issues.update({
-                owner: context.repo.owner, repo: context.repo.repo, issue_number: summary.number,
-                title: summaryTitle, body: summaryBody, state: "open",
-              });
-            }
-
-            if (
-              !isObject(report.plan)
-              || (report.plan.error !== null && typeof report.plan.error !== "string")
-              || !isObject(report.plan.packages)
-              || typeof report.plan.searchTruncated !== "boolean"
-            ) {
-              fail("The version-check report contains invalid automatic planning state.");
-            }
-            const verificationStatuses = ["verified", "not-needed", "incomplete", "failed", "infrastructure-failed"];
-            if (!isObject(report.verification)
-              || (report.verification.error !== null && typeof report.verification.error !== "string")
-              || !verificationStatuses.includes(report.verification.status)) {
-              fail("The version-check report contains invalid automatic verification state.");
-            }
-            if (report.verification.status === "infrastructure-failed") {
-              core.warning("Skipping trustee decision reconciliation because automatic verification hit an infrastructure failure.");
-              return;
-            }
-            if (report.manualAnalysis.error !== null || report.manualAnalysis.searchTruncated === true) {
-              core.warning("Skipping trustee decision reconciliation because manual-intervention analysis failed or was truncated.");
-              return;
-            }
-            if (report.manualInterventionsDeferred === true) {
-              core.warning("Skipping trustee decision reconciliation until residual decisions are recomputed against the newly published baseline.");
-              return;
-            }
-            if (!Array.isArray(report.manualInterventions)) fail("The version-check report is missing the manualInterventions array.");
-
-            const componentPattern = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,127}$/;
-            const fingerprintPattern = /^[A-Za-z0-9][A-Za-z0-9._:/+=-]{0,199}$/;
-            const interventions = report.manualInterventions.map((intervention, index) => {
-              const location = `manualInterventions[${index}]`;
-              if (!isObject(intervention)) fail(`${location} must be an object.`);
-              const { component, fingerprint, title, markdownBody, removal } = intervention;
-              if (typeof component !== "string" || !componentPattern.test(component)) fail(`${location}.component is not a safe stable component identifier.`);
-              if (typeof fingerprint !== "string" || !fingerprintPattern.test(fingerprint)) fail(`${location}.fingerprint is not a safe non-empty fingerprint.`);
-              if (typeof title !== "string" || title.trim() !== title || title.length === 0 || title.length > 256 || /[\r\n]/.test(title)) {
-                fail(`${location}.title must be a non-empty single-line GitHub issue title.`);
-              }
-              if (typeof markdownBody !== "string" || markdownBody.trim().length === 0 || hasReservedMarker(markdownBody)) {
-                fail(`${location}.markdownBody must be non-empty Markdown without reserved markers.`);
-              }
-              if (!isObject(removal) || typeof removal.verified !== "boolean" || !isObject(removal.payload)) {
-                fail(`${location}.removal must contain a Boolean verified field and an object payload.`);
-              }
-              const payloadKeys = Object.keys(removal.payload);
-              if (payloadKeys.some(key => !["expectedBaseline", "compiler", "packages"].includes(key))) {
-                fail(`${location}.removal.payload contains an unexpected field.`);
-              }
-              if (typeof removal.payload.expectedBaseline !== "string" || removal.payload.expectedBaseline.length === 0) {
-                fail(`${location}.removal.payload.expectedBaseline must be a non-empty string.`);
-              }
-              if ("compiler" in removal.payload && typeof removal.payload.compiler !== "string") {
-                fail(`${location}.removal.payload.compiler must be a string when present.`);
-              }
-              if (!isObject(removal.payload.packages)) {
-                fail(`${location}.removal.payload.packages must be an object.`);
-              }
-              if (Object.values(removal.payload.packages).some(value => value !== null && typeof value !== "string")) {
-                fail(`${location}.removal.payload.packages values must be strings or null removals.`);
-              }
-              if (removal.verified && !Object.values(removal.payload.packages).some(value => value === null)) {
-                fail(`${location}.removal.payload.packages must contain a removal when verified is true.`);
-              }
-              const payloadHeading = removal.verified ? "## Compile-verified removal payload" : "## Diagnostic payload (not compile-verified)";
-              const payloadNote = removal.verified
-                ? "The planner atomically verified this package-set payload. A trustee must review it before taking action."
-                : "The planner did not find a compile-verified removal for this component. This payload is diagnostic only and must not be applied as a verified plan.";
-              const body = [
-                decisionMarker, markerFor(componentMarkerPrefix, component), markerFor(fingerprintMarkerPrefix, fingerprint), "",
-                normalize(markdownBody).trimEnd(), "", payloadHeading, "", payloadNote, "",
-                "```json", JSON.stringify(removal.payload, null, 2), "```",
-              ].join("\n");
-              if (body.length > 65536) fail(`${location} produces a GitHub issue body larger than 65536 characters.`);
-              return { body, component, fingerprint, title };
-            });
-
-            const components = interventions.map(intervention => intervention.component);
-            const fingerprints = interventions.map(intervention => intervention.fingerprint);
-            if (new Set(components).size !== components.length) fail("manualInterventions contains duplicate component identifiers.");
-            if (new Set(fingerprints).size !== fingerprints.length) fail("manualInterventions contains duplicate fingerprints.");
-
-            const decisionIssues = allIssues.filter(issue => hasExactMarker(issue, decisionMarker));
-            if (decisionIssues.some(issue => hasExactMarker(issue, summaryMarker))) fail("An issue contains both summary and decision markers.");
-            const existingByComponent = new Map();
-            const existingByFingerprint = new Map();
-            for (const issue of decisionIssues) {
-              const issueLines = lines(issue.body);
-              if (issueLines.filter(line => line === decisionMarker).length !== 1) fail(`Decision issue #${issue.number} has duplicate decision markers.`);
-              const componentMarkers = issueLines.filter(line => line.startsWith(componentMarkerPrefix) && line.endsWith(markerSuffix));
-              const fingerprintMarkers = issueLines.filter(line => line.startsWith(fingerprintMarkerPrefix) && line.endsWith(markerSuffix));
-              if (componentMarkers.length !== 1 || fingerprintMarkers.length !== 1) fail(`Decision issue #${issue.number} has malformed identity markers.`);
-              const component = componentMarkers[0].slice(componentMarkerPrefix.length, -markerSuffix.length);
-              const fingerprint = fingerprintMarkers[0].slice(fingerprintMarkerPrefix.length, -markerSuffix.length);
-              if (!componentPattern.test(component) || !fingerprintPattern.test(fingerprint)
-                || componentMarkers[0] !== markerFor(componentMarkerPrefix, component)
-                || fingerprintMarkers[0] !== markerFor(fingerprintMarkerPrefix, fingerprint)) {
-                fail(`Decision issue #${issue.number} has invalid identity markers.`);
-              }
-              if (existingByComponent.has(component)) fail(`Multiple decision issues have the exact component marker for ${component}.`);
-              if (existingByFingerprint.has(fingerprint)) fail(`Multiple decision issues have the exact fingerprint marker ${fingerprint}.`);
-              existingByComponent.set(component, issue);
-              existingByFingerprint.set(fingerprint, issue);
-            }
-            for (const intervention of interventions) {
-              const fingerprintOwner = existingByFingerprint.get(intervention.fingerprint);
-              if (fingerprintOwner && fingerprintOwner !== existingByComponent.get(intervention.component)) {
-                fail(`Fingerprint ${intervention.fingerprint} belongs to decision issue #${fingerprintOwner.number} for another component.`);
-              }
-            }
-
-            for (const intervention of interventions) {
-              const existing = existingByComponent.get(intervention.component);
-              if (!existing) {
-                await github.rest.issues.create({ owner: context.repo.owner, repo: context.repo.repo, title: intervention.title, body: intervention.body });
-              } else if (existing.state !== "open" || existing.title !== intervention.title || normalize(existing.body) !== intervention.body) {
-                await github.rest.issues.update({
-                  owner: context.repo.owner, repo: context.repo.repo, issue_number: existing.number,
-                  title: intervention.title, body: intervention.body, state: "open",
-                });
-              }
-            }
diff --git a/foreign/src/Foreign/Octokit.purs b/foreign/src/Foreign/Octokit.purs
index 92637620..3e040e91 100644
--- a/foreign/src/Foreign/Octokit.purs
+++ b/foreign/src/Foreign/Octokit.purs
@@ -11,6 +11,7 @@ module Registry.Foreign.Octokit
   , GitHubError(..)
   , GitHubRoute(..)
   , GitHubToken(..)
+  , Issue
   , IssueNumber(..)
   , JSArgs(..)
   , Octokit
@@ -22,6 +23,7 @@ module Registry.Foreign.Octokit
   , atKey
   , closeIssueRequest
   , createCommentRequest
+  , createIssueRequest
   , decodeBase64Content
   , getCommitDateRequest
   , getContentRequest
@@ -30,6 +32,7 @@ module Registry.Foreign.Octokit
   , githubErrorCodec
   , isPermanentGitHubError
   , listCommitsSinceRequest
+  , listIssuesRequest
   , listTagsRequest
   , listTeamMembersRequest
   , CommitSha
@@ -40,6 +43,7 @@ module Registry.Foreign.Octokit
   , rateLimitRequest
   , request
   , unsafeToJSArgs
+  , updateIssueRequest
   ) where
 
 import Prelude
@@ -52,6 +56,7 @@ import Data.Array as Array
 import Data.Bifunctor (lmap)
 import Data.Codec as Codec
 import Data.Codec.JSON as CJ
+import Data.Codec.JSON.Common as CJ.Common
 import Data.Codec.JSON.Record as CJ.Record
 import Data.Codec.JSON.Variant as CJ.Variant
 import Data.DateTime (DateTime)
@@ -123,6 +128,67 @@ newtype IssueNumber = IssueNumber Int
 instance Newtype IssueNumber Int
 derive newtype instance Eq IssueNumber
 
+type Issue =
+  { body :: Maybe String
+  , isPullRequest :: Boolean
+  , number :: IssueNumber
+  , state :: String
+  , title :: String
+  }
+
+issueCodec :: CJ.Codec Issue
+issueCodec = Codec.codec' decode (const $ CJ.encode CJ.null unit)
+  where
+  decode json = except do
+    decoded <- CJ.decode issueRepCodec json
+    pure
+      { body: decoded.body
+      , isPullRequest: Maybe.isJust decoded.pull_request
+      , number: IssueNumber decoded.number
+      , state: decoded.state
+      , title: decoded.title
+      }
+
+  issueRepCodec = CJ.named "Issue" $ CJ.Record.object
+    { body: CJ.Common.nullable CJ.string
+    , number: CJ.int
+    , pull_request: CJ.Record.optional CJ.json
+    , state: CJ.string
+    , title: CJ.string
+    }
+
+-- | List all issues and pull requests in a repository.
+listIssuesRequest :: Address -> Request (Array Issue)
+listIssuesRequest address =
+  { route: GitHubRoute GET [ "repos", address.owner, address.repo, "issues" ] (Map.singleton "state" "all")
+  , headers: Object.empty
+  , args: noArgs
+  , paginate: true
+  , codec: CJ.array issueCodec
+  }
+
+-- | Create an issue. Requires authentication.
+createIssueRequest :: { address :: Address, body :: String, title :: String } -> Request Unit
+createIssueRequest { address, body, title } =
+  { route: GitHubRoute POST [ "repos", address.owner, address.repo, "issues" ] Map.empty
+  , headers: Object.empty
+  , args: unsafeToJSArgs { body, title }
+  , paginate: false
+  , codec: Codec.codec' (\_ -> pure unit) (CJ.encode CJ.null)
+  }
+
+-- | Replace an issue's title/body and set its state. Requires authentication.
+updateIssueRequest
+  :: { address :: Address, body :: String, issue :: IssueNumber, state :: String, title :: String }
+  -> Request Unit
+updateIssueRequest { address, body, issue: IssueNumber issue, state, title } =
+  { route: GitHubRoute PATCH [ "repos", address.owner, address.repo, "issues", Int.toStringAs Int.decimal issue ] Map.empty
+  , headers: Object.empty
+  , args: unsafeToJSArgs { body, state, title }
+  , paginate: false
+  , codec: Codec.codec' (\_ -> pure unit) (CJ.encode CJ.null)
+  }
+
 -- | A team within a GitHub organization
 type Team = { org :: String, team :: String }
 
diff --git a/scripts/src/PackageSetPlanner.purs b/scripts/src/PackageSetPlanner.purs
index 093b4c7a..d5a3d7ca 100644
--- a/scripts/src/PackageSetPlanner.purs
+++ b/scripts/src/PackageSetPlanner.purs
@@ -12,7 +12,9 @@
 -- | truncated (possibly non-maximal), but never verified unless its exact
 -- | payload compiled. Residual latest updates are probed for the manual lane;
 -- | compiler source paths seed reverse-dependency removal closure, and a
--- | removal is called verified only after that exact payload also compiles.
+-- | failed removal probe can add newly exposed blockers and their reverse
+-- | dependants. A removal is called verified only after that exact payload
+-- | compiles.
 -- | Infrastructure failures are kept separate from compiler incompatibility.
 module Registry.Scripts.PackageSetPlanner where
 
@@ -59,6 +61,7 @@ type ManualIntervention =
   { compilerError :: Maybe String
   , packages :: Map PackageName Version
   , removals :: Array PackageName
+  , targets :: Array PackageName
   , verification :: Verification
   }
 
@@ -76,6 +79,12 @@ data ProbeResult
 
 derive instance Eq ProbeResult
 
+data ManualRemovalResult
+  = RemovalVerified Int (Set PackageName) (Array String)
+  | RemovalFailed Int (Set PackageName) (Array String)
+  | RemovalAnalysisFailed Int String
+  | RemovalSearchTruncated Int
+
 type Probe r = PackageSet -> PackageSets.ChangeSet -> Run r ProbeResult
 
 automaticProbeBudget :: Int
@@ -538,6 +547,7 @@ planManualInterventions probe packageSet manifests components automatic = go emp
                               [ { compilerError: Just compilerError
                                 , packages
                                 , removals: []
+                                , targets: Array.fromFoldable $ Map.keys latest
                                 , verification:
                                     { error: Just "The compiler failure did not identify an unchanged package with a removable reverse-dependency closure."
                                     , status: "unresolved"
@@ -547,47 +557,87 @@ planManualInterventions probe packageSet manifests components automatic = go emp
                           }
                       )
                       rest
-                  else if state.attempts + 1 >= manualProbeBudget then
-                    pure $ state
-                      { attempts = state.attempts + 1
-                      , truncated = true
-                      }
                   else do
-                    let removalChanges = Map.union (map (const PackageSets.Remove) (Map.fromFoldable (map (\name -> Tuple name unit) (Array.fromFoldable removals)))) changes
-                    probe packageSet removalChanges >>= case _ of
-                      Compiles ->
+                    probeManualRemovals probe packageSet manifests packages removals (state.attempts + 1) >>= case _ of
+                      RemovalVerified attempts verifiedRemovals additionalEvidence ->
                         go
                           ( state
-                              { attempts = state.attempts + 2
+                              { attempts = attempts
                               , interventions = state.interventions <>
-                                  [ { compilerError: Just compilerError
+                                  [ { compilerError: Just $ combineCompilerEvidence compilerError additionalEvidence
                                     , packages
-                                    , removals: Array.fromFoldable removals
+                                    , removals: Array.fromFoldable verifiedRemovals
+                                    , targets: Array.fromFoldable $ Map.keys latest
                                     , verification: { error: Nothing, status: "verified" }
                                     }
                                   ]
                               }
                           )
                           rest
-                      CompilationFailure error ->
+                      RemovalFailed attempts failedRemovals additionalEvidence ->
                         go
                           ( state
-                              { attempts = state.attempts + 2
+                              { attempts = attempts
                               , interventions = state.interventions <>
-                                  [ { compilerError: Just compilerError
+                                  [ { compilerError: Just $ combineCompilerEvidence compilerError additionalEvidence
                                     , packages
-                                    , removals: Array.fromFoldable removals
-                                    , verification: { error: Just error, status: "failed" }
+                                    , removals: Array.fromFoldable failedRemovals
+                                    , targets: Array.fromFoldable $ Map.keys latest
+                                    , verification: { error: Array.last additionalEvidence, status: "failed" }
                                     }
                                   ]
                               }
                           )
                           rest
-                      InfrastructureFailure error ->
+                      RemovalAnalysisFailed attempts error ->
                         pure $ state
-                          { attempts = state.attempts + 2
+                          { attempts = attempts
                           , error = Just error
                           }
+                      RemovalSearchTruncated attempts ->
+                        pure $ state
+                          { attempts = attempts
+                          , truncated = true
+                          }
+
+probeManualRemovals
+  :: forall r
+   . Probe r
+  -> PackageSet
+  -> ManifestIndex
+  -> Map PackageName Version
+  -> Set PackageName
+  -> Int
+  -> Run r ManualRemovalResult
+probeManualRemovals probe packageSet manifests packages = go []
+  where
+  proposed = applyUpdates packageSet packages
+
+  go evidence removals attempts
+    | attempts >= manualProbeBudget = pure $ RemovalSearchTruncated attempts
+    | otherwise = do
+        let changes = map PackageSets.Update packages
+        let removalChanges = Map.union (map (const PackageSets.Remove) (Map.fromFoldable (map (\name -> Tuple name unit) (Array.fromFoldable removals)))) changes
+        probe packageSet removalChanges >>= case _ of
+          Compiles -> pure $ RemovalVerified (attempts + 1) removals evidence
+          InfrastructureFailure error -> pure $ RemovalAnalysisFailed (attempts + 1) error
+          CompilationFailure error -> do
+            let nextEvidence = evidence <> [ error ]
+            let remaining = Foldable.foldr Map.delete proposed removals
+            let seeds = compilerFailurePackages packageSet packages error
+            case reverseDependencyClosure remaining manifests seeds of
+              Left analysisError -> pure $ RemovalAnalysisFailed (attempts + 1) analysisError
+              Right closure -> do
+                let additions = Set.difference closure (Map.keys packages)
+                let next = Set.union removals additions
+                if next == removals then
+                  pure $ RemovalFailed (attempts + 1) removals nextEvidence
+                else
+                  go nextEvidence next (attempts + 1)
+
+combineCompilerEvidence :: String -> Array String -> String
+combineCompilerEvidence initial additional =
+  String.joinWith "\n\n--- Next compile probe exposed another blocker ---\n\n" ([ initial ] <> additional)
 
 latestUpdates :: Array Candidate -> Map PackageName Version
 latestUpdates = Map.fromFoldable <<< Array.mapMaybe \candidate -> Tuple candidate.name <$> Array.head candidate.versions
diff --git a/scripts/src/VersionCheck.purs b/scripts/src/VersionCheck.purs
index 3fc3b0f0..8ebb0ad3 100644
--- a/scripts/src/VersionCheck.purs
+++ b/scripts/src/VersionCheck.purs
@@ -25,6 +25,7 @@ import Data.Map as Map
 import Data.Set as Set
 import Data.String as String
 import Data.Time.Duration (Days(..), Hours(..))
+import Effect.Aff as Aff
 import Effect.Class.Console as Console
 import JSON as JSON
 import Node.FS.Aff as FS.Aff
@@ -43,6 +44,8 @@ import Registry.App.Effect.Registry as Registry
 import Registry.App.Effect.Storage (STORAGE)
 import Registry.App.Effect.Storage as Storage
 import Registry.Foreign.FSExtra as FS.Extra
+import Registry.Foreign.Octokit (GitHubToken(..))
+import Registry.Foreign.Octokit as Octokit
 import Registry.Internal.Codec as Internal.Codec
 import Registry.Manifest (Manifest(..))
 import Registry.ManifestIndex (ManifestIndex)
@@ -56,6 +59,7 @@ import Registry.Range (Range)
 import Registry.Range as Range
 import Registry.Scripts.PackageSetPlanner as Planner
 import Registry.Scripts.PackageSetUpdater as PackageSetUpdater
+import Registry.Scripts.VersionCheck.GitHub as VersionCheck.GitHub
 import Registry.Sha256 as Sha256
 import Registry.Version (Version)
 import Registry.Version as Version
@@ -67,6 +71,7 @@ import Run.Except as Except
 type Options =
   { markdown :: Maybe FilePath
   , output :: Maybe FilePath
+  , reconcileIssues :: Boolean
   , submit :: Boolean
   }
 
@@ -76,9 +81,10 @@ parser = ado
   -- now intrinsic to planning and is always performed.
   _ <- Arg.flag [ "--verify" ] "Compatibility flag; compile-guided planning always verifies the result." # Arg.boolean # Arg.default false
   submit <- Arg.flag [ "--submit" ] "Submit the exact verified automatic plan to the registry API." # Arg.boolean # Arg.default false
+  reconcileIssues <- Arg.flag [ "--reconcile-issues" ] "Update the rolling report and trustee decision issues in purescript/registry-dev." # Arg.boolean # Arg.default false
   output <- Arg.argument [ "--output" ] "Write the structured report as JSON." # Arg.optional
   markdown <- Arg.argument [ "--markdown" ] "Write the human-readable report as Markdown." # Arg.optional
-  in { markdown, output, submit }
+  in { markdown, output, reconcileIssues, submit }
 
 main :: Effect Unit
 main = launchAff_ do
@@ -124,9 +130,34 @@ main = launchAff_ do
         Console.log markdown
         for_ options.output \path -> writeJsonFile reportCodec path result.report
         for_ options.markdown \path -> FS.Aff.writeTextFile UTF8 path (markdown <> "\n")
+        reconciliationError <-
+          if options.reconcileIssues then do
+            token <- liftEffect (Process.lookupEnv "GITHUB_TOKEN") >>= case _ of
+              Nothing -> Aff.throwError $ Aff.error "GITHUB_TOKEN is required with --reconcile-issues."
+              Just value -> pure $ GitHubToken value
+            octokit <- Octokit.newOctokit token resourceEnv.githubApiUrl
+            VersionCheck.GitHub.reconcile octokit
+              { interventions: result.report.manualInterventions <#> \intervention ->
+                  { component: intervention.component
+                  , fingerprint: intervention.fingerprint
+                  , markdownBody: intervention.markdownBody
+                  , payload: JSON.printIndented $ CJ.encode Operation.packageSetOperationCodec intervention.removal.payload
+                  , removalVerified: intervention.removal.verified
+                  , title: intervention.title
+                  }
+              , markdown
+              , reconcileDecisions:
+                  result.report.verification.status /= "infrastructure-failed"
+                    && isNothing result.report.manualAnalysis.error
+                    && not result.report.manualAnalysis.searchTruncated
+                    && not result.report.manualInterventionsDeferred
+              }
+          else
+            pure $ Right unit
         let
           fatalError = case result.submissionError of
             Just error -> Just error
+            Nothing | Left error <- reconciliationError -> Just error
             Nothing | result.report.verification.status == "infrastructure-failed" ->
               Just $ fromMaybe "Package set planning failed because of an infrastructure error." result.report.verification.error
             Nothing | Just error <- result.report.manualAnalysis.error -> Just error
@@ -368,7 +399,8 @@ manualReport baseline compiler intervention = do
   let removals = Map.fromFoldable $ intervention.removals <#> \name -> Tuple name Nothing
   let update = { compiler: Nothing, packages: Map.union removals (map Just intervention.packages) }
   let payload = Operation.PackageSetUpdateFrom baseline update
-  let names = Array.sort $ map PackageName.print (Map.keys update.packages # Array.fromFoldable)
+  let affectedNames = Array.sort $ map PackageName.print (Map.keys update.packages # Array.fromFoldable)
+  let targetNames = Array.sort $ map PackageName.print intervention.targets
   let
     decision = String.joinWith "|"
       [ Version.print compiler
@@ -378,11 +410,11 @@ manualReport baseline compiler intervention = do
       , fromMaybe "" intervention.compilerError
       ]
   decisionHash <- Sha256.print <$> Sha256.hashString decision
-  componentHash <- Sha256.print <$> Sha256.hashString (String.joinWith "|" names)
+  componentHash <- Sha256.print <$> Sha256.hashString (String.joinWith "|" targetNames)
   let safeComponentHash = componentHash # String.replaceAll (String.Pattern "+") (String.Replacement "-") # String.replaceAll (String.Pattern "/") (String.Replacement "_") # String.replaceAll (String.Pattern "=") (String.Replacement "")
-  let component = "packages-" <> String.take 72 (String.joinWith "-" names) <> "-" <> String.take 32 safeComponentHash
+  let component = "packages-" <> String.take 72 (String.joinWith "-" targetNames) <> "-" <> String.take 32 safeComponentHash
   let verified = intervention.verification.status == "verified" && not (Array.null intervention.removals)
-  let title = String.trim $ String.take 256 $ "Package set intervention: " <> String.joinWith ", " names
+  let title = String.trim $ String.take 256 $ "Package set intervention: " <> String.joinWith ", " affectedNames
   let
     markdownBody = String.joinWith "\n"
       [ "The planner tested this component with PureScript `" <> Version.print compiler <> "` against package set `" <> Version.print baseline <> "`."
diff --git a/scripts/src/VersionCheck/GitHub.purs b/scripts/src/VersionCheck/GitHub.purs
new file mode 100644
index 00000000..8353aae2
--- /dev/null
+++ b/scripts/src/VersionCheck/GitHub.purs
@@ -0,0 +1,249 @@
+-- | GitHub issue reconciliation for the version-check script. Workflow files
+-- | should only invoke the script; report validation and issue lifecycle belong
+-- | here where they can be typed and unit tested.
+module Registry.Scripts.VersionCheck.GitHub where
+
+import Registry.App.Prelude
+
+import Data.Array as Array
+import Data.Foldable as Foldable
+import Data.Map as Map
+import Data.Set as Set
+import Data.String as String
+import Data.String.CodeUnits as CodeUnits
+import Registry.Foreign.Octokit (Issue, IssueNumber, Octokit)
+import Registry.Foreign.Octokit as Octokit
+
+type Intervention =
+  { component :: String
+  , fingerprint :: String
+  , markdownBody :: String
+  , payload :: String
+  , removalVerified :: Boolean
+  , title :: String
+  }
+
+type ReconciliationInput =
+  { interventions :: Array Intervention
+  , markdown :: String
+  , reconcileDecisions :: Boolean
+  }
+
+data IssueMutation
+  = CreateIssue { body :: String, title :: String }
+  | UpdateIssue { body :: String, issue :: IssueNumber, state :: String, title :: String }
+
+derive instance Eq IssueMutation
+
+registryDev :: Octokit.Address
+registryDev = { owner: "purescript", repo: "registry-dev" }
+
+summaryMarker :: String
+summaryMarker = "<!-- registry-version-check:summary:v1 -->"
+
+decisionMarker :: String
+decisionMarker = "<!-- registry-version-check:decision:v1 -->"
+
+componentMarkerPrefix :: String
+componentMarkerPrefix = "<!-- registry-version-check:component:"
+
+fingerprintMarkerPrefix :: String
+fingerprintMarkerPrefix = "<!-- registry-version-check:fingerprint:"
+
+markerSuffix :: String
+markerSuffix = " -->"
+
+summaryTitle :: String
+summaryTitle = "Package set planning report"
+
+reconcile :: Octokit -> ReconciliationInput -> Aff (Either String Unit)
+reconcile octokit input =
+  Octokit.request octokit (Octokit.listIssuesRequest registryDev) >>= case _ of
+    Left error -> pure $ Left $ "Could not list registry-dev issues: " <> Octokit.printGitHubError error
+    Right allItems -> case planIssueReconciliation (input { reconcileDecisions = false }) allItems of
+      Left error -> pure $ Left error
+      Right summaryMutations -> applyMutations summaryMutations >>= case _ of
+        Left error -> pure $ Left error
+        Right _
+          | not input.reconcileDecisions -> pure $ Right unit
+          | otherwise -> case planIssueReconciliation input allItems of
+              Left error -> pure $ Left error
+              Right mutations -> applyMutations $ Array.filter (not <<< isSummaryMutation) mutations
+  where
+  isSummaryMutation = case _ of
+    CreateIssue issue -> isJust $ String.stripPrefix (String.Pattern summaryMarker) issue.body
+    UpdateIssue issue -> isJust $ String.stripPrefix (String.Pattern summaryMarker) issue.body
+
+  applyMutations mutations = case Array.uncons mutations of
+    Nothing -> pure $ Right unit
+    Just { head: mutation, tail } -> do
+      result <- case mutation of
+        CreateIssue issue -> Octokit.request octokit $ Octokit.createIssueRequest
+          { address: registryDev, body: issue.body, title: issue.title }
+        UpdateIssue issue -> Octokit.request octokit $ Octokit.updateIssueRequest
+          { address: registryDev, body: issue.body, issue: issue.issue, state: issue.state, title: issue.title }
+      case result of
+        Left error -> pure $ Left $ "Could not reconcile registry-dev issues: " <> Octokit.printGitHubError error
+        Right _ -> applyMutations tail
+
+planIssueReconciliation :: ReconciliationInput -> Array Issue -> Either String (Array IssueMutation)
+planIssueReconciliation input allItems = do
+  let markdown = trimTrailingNewlines $ normalize input.markdown
+  when (hasReservedMarker markdown) $ Left "The generated Markdown contains a reserved automation marker."
+  let summaryBody = summaryMarker <> "\n\n" <> markdown <> "\n"
+  when (CodeUnits.length summaryBody > 65_536) $ Left "The rolling report issue body is larger than 65536 characters."
+
+  let allIssues = Array.filter (not <<< _.isPullRequest) allItems
+  let summaryIssues = Array.filter (flip hasExactMarker summaryMarker) allIssues
+  when (Array.length summaryIssues > 1) $ Left "Found multiple rolling issues with the exact summary marker."
+  when (any (hasDuplicateMarker summaryMarker) summaryIssues) $ Left "The rolling issue has duplicate summary markers."
+  when (any (flip hasExactMarker decisionMarker) summaryIssues) $ Left "An issue contains both summary and decision markers."
+
+  let
+    summaryMutations = case Array.head summaryIssues of
+      Nothing -> [ CreateIssue { title: summaryTitle, body: summaryBody } ]
+      Just issue
+        | issue.state /= "open" || issue.title /= summaryTitle || normalize (fromMaybe "" issue.body) /= summaryBody ->
+            [ UpdateIssue { issue: issue.number, title: summaryTitle, body: summaryBody, state: "open" } ]
+      Just _ -> []
+
+  if not input.reconcileDecisions then pure summaryMutations
+  else do
+    planned <- traverse prepareIntervention input.interventions
+    let components = map _.component planned
+    let fingerprints = map _.fingerprint planned
+    when (Set.size (Set.fromFoldable components) /= Array.length components) $ Left "Manual interventions contain duplicate component identifiers."
+    when (Set.size (Set.fromFoldable fingerprints) /= Array.length fingerprints) $ Left "Manual interventions contain duplicate fingerprints."
+
+    let decisionIssues = Array.filter (flip hasExactMarker decisionMarker) allIssues
+    when (any (flip hasExactMarker summaryMarker) decisionIssues) $ Left "An issue contains both summary and decision markers."
+    indexed <- indexDecisionIssues decisionIssues
+
+    let
+      activeMutations = planned >>= \intervention -> case Map.lookup intervention.component indexed.byComponent of
+        Nothing -> [ CreateIssue { title: intervention.title, body: intervention.body } ]
+        Just issue
+          | issue.state /= "open" || issue.title /= intervention.title || normalize (fromMaybe "" issue.body) /= intervention.body ->
+              [ UpdateIssue { issue: issue.number, title: intervention.title, body: intervention.body, state: "open" } ]
+        Just _ -> []
+
+    for_ planned \intervention -> case Map.lookup intervention.fingerprint indexed.byFingerprint of
+      Just owner | Just owner /= Map.lookup intervention.component indexed.byComponent ->
+        Left $ "Fingerprint " <> intervention.fingerprint <> " belongs to a decision issue for another component."
+      _ -> pure unit
+
+    pure $ summaryMutations <> activeMutations
+
+type PreparedIntervention =
+  { body :: String
+  , component :: String
+  , fingerprint :: String
+  , title :: String
+  }
+
+prepareIntervention :: Intervention -> Either String PreparedIntervention
+prepareIntervention intervention = do
+  unless (safeMarkerValue 128 intervention.component) $ Left "A manual intervention has an unsafe component identifier."
+  unless (safeMarkerValue 200 intervention.fingerprint) $ Left "A manual intervention has an unsafe fingerprint."
+  when
+    ( String.trim intervention.title /= intervention.title
+        || String.contains (String.Pattern "\n") intervention.title
+        || String.contains (String.Pattern "\r") intervention.title
+        || CodeUnits.length intervention.title
+        == 0
+        || CodeUnits.length intervention.title
+        > 256
+    )
+    $ Left "A manual intervention has an invalid issue title."
+  when (String.trim intervention.markdownBody == "" || hasReservedMarker intervention.markdownBody) $
+    Left "A manual intervention has invalid Markdown."
+
+  let payloadHeading = if intervention.removalVerified then "## Compile-verified removal payload" else "## Diagnostic payload (not compile-verified)"
+  let
+    payloadNote =
+      if intervention.removalVerified then
+        "The planner atomically verified this package-set payload. A trustee must review it before taking action."
+      else
+        "The planner did not find a compile-verified removal for this component. This payload is diagnostic only and must not be applied as a verified plan."
+  let
+    body = String.joinWith "\n"
+      [ decisionMarker
+      , markerFor componentMarkerPrefix intervention.component
+      , markerFor fingerprintMarkerPrefix intervention.fingerprint
+      , ""
+      , trimTrailingNewlines $ normalize intervention.markdownBody
+      , ""
+      , payloadHeading
+      , ""
+      , payloadNote
+      , ""
+      , "```json"
+      , intervention.payload
+      , "```"
+      ]
+  when (CodeUnits.length body > 65_536) $ Left "A manual intervention issue body is larger than 65536 characters."
+  pure { body, component: intervention.component, fingerprint: intervention.fingerprint, title: intervention.title }
+
+type IndexedIssues =
+  { byComponent :: Map String Issue
+  , byFingerprint :: Map String Issue
+  }
+
+indexDecisionIssues :: Array Issue -> Either String IndexedIssues
+indexDecisionIssues = Foldable.foldM insert { byComponent: Map.empty, byFingerprint: Map.empty }
+  where
+  insert indexed issue = do
+    when (hasDuplicateMarker decisionMarker issue) $ Left "A decision issue has duplicate decision markers."
+    component <- oneMarker componentMarkerPrefix issue
+    fingerprint <- oneMarker fingerprintMarkerPrefix issue
+    unless (safeMarkerValue 128 component && safeMarkerValue 200 fingerprint) $ Left "A decision issue has invalid identity markers."
+    when (Map.member component indexed.byComponent) $ Left "Multiple decision issues have the same component marker."
+    when (Map.member fingerprint indexed.byFingerprint) $ Left "Multiple decision issues have the same fingerprint marker."
+    pure
+      { byComponent: Map.insert component issue indexed.byComponent
+      , byFingerprint: Map.insert fingerprint issue indexed.byFingerprint
+      }
+
+oneMarker :: String -> Issue -> Either String String
+oneMarker prefix issue = case markers prefix issue of
+  [ value ] | markerFor prefix value `Array.elem` issueLines issue -> pure value
+  _ -> Left "A decision issue has malformed identity markers."
+
+markers :: String -> Issue -> Array String
+markers prefix issue = Array.mapMaybe extract (issueLines issue)
+  where
+  extract line = String.stripPrefix (String.Pattern prefix) line >>= String.stripSuffix (String.Pattern markerSuffix)
+
+markerFor :: String -> String -> String
+markerFor prefix value = prefix <> value <> markerSuffix
+
+safeMarkerValue :: Int -> String -> Boolean
+safeMarkerValue limit value =
+  CodeUnits.length value > 0
+    && CodeUnits.length value
+    <= limit
+    && not (String.contains (String.Pattern "\n") value)
+    && not (String.contains (String.Pattern "\r") value)
+    && not (String.contains (String.Pattern "<!--") value)
+    && not (String.contains (String.Pattern "-->") value)
+
+hasReservedMarker :: String -> Boolean
+hasReservedMarker = String.split (String.Pattern "\n")
+  >>> any (isJust <<< String.stripPrefix (String.Pattern "<!-- registry-version-check:"))
+
+hasExactMarker :: Issue -> String -> Boolean
+hasExactMarker issue marker = marker `Array.elem` issueLines issue
+
+hasDuplicateMarker :: String -> Issue -> Boolean
+hasDuplicateMarker marker issue = Array.length (Array.filter (_ == marker) $ issueLines issue) /= 1
+
+issueLines :: Issue -> Array String
+issueLines issue = String.split (String.Pattern "\n") $ normalize $ fromMaybe "" issue.body
+
+normalize :: String -> String
+normalize = String.replaceAll (String.Pattern "\r\n") (String.Replacement "\n")
+
+trimTrailingNewlines :: String -> String
+trimTrailingNewlines value = case String.stripSuffix (String.Pattern "\n") value of
+  Nothing -> value
+  Just trimmed -> trimTrailingNewlines trimmed
diff --git a/scripts/test/Main.purs b/scripts/test/Main.purs
index 0bec8d98..2aa8a6ba 100644
--- a/scripts/test/Main.purs
+++ b/scripts/test/Main.purs
@@ -10,6 +10,8 @@ import Data.Set as Set
 import Data.String as String
 import Data.Time.Duration (Hours(..))
 import Registry.App.Effect.PackageSets (Change(..), ChangeSet)
+import Registry.Foreign.Octokit (Issue, IssueNumber(..))
+import Registry.Foreign.Octokit as Octokit
 import Registry.Manifest (Manifest)
 import Registry.ManifestIndex (IncludeRanges(..), ManifestIndex)
 import Registry.ManifestIndex as ManifestIndex
@@ -22,6 +24,7 @@ import Registry.PackageSet as PackageSet
 import Registry.Scripts.PackageSetPlanner as Planner
 import Registry.Scripts.PackageSetUpdater as PackageSetUpdater
 import Registry.Scripts.VersionCheck as VersionCheck
+import Registry.Scripts.VersionCheck.GitHub as VersionCheck.GitHub
 import Registry.Test.Assert as Assert
 import Registry.Test.Utils as Utils
 import Registry.Version (Version)
@@ -266,6 +269,99 @@ main = runSpecAndExitProcess [ consoleReporter ] do
       String.contains (String.Pattern "Advisory range diagnostics") (VersionCheck.renderMarkdown report)
         `Assert.shouldEqual` true
 
+    Spec.it "extends a removal proposal when compilation reveals another blocker" do
+      let
+        packageSet = mkPackageSet $ Map.fromFoldable
+          [ Tuple (name "target") (version "1.0.0")
+          , Tuple (name "blocked-a") (version "1.0.0")
+          , Tuple (name "blocked-b") (version "1.0.0")
+          ]
+        manifests = manifestIndex
+          [ Utils.unsafeManifest "target" "1.0.0" []
+          , Utils.unsafeManifest "target" "2.0.0" []
+          , Utils.unsafeManifest "blocked-a" "1.0.0" []
+          , Utils.unsafeManifest "blocked-b" "1.0.0" []
+          ]
+        candidates =
+          [ { current: Just (version "1.0.0"), name: name "target", versions: [ version "2.0.0" ] } ]
+        failure package = String.joinWith "\n"
+          [ "Error 1 of 1"
+          , "  File: packages/" <> package <> "@1.0.0/src/Main.purs"
+          ]
+        probe _ changes
+          | Map.lookup (name "target") changes /= Just (Update (version "2.0.0")) = pure Planner.Compiles
+          | Map.lookup (name "blocked-a") changes /= Just Remove = pure $ Planner.CompilationFailure (failure "blocked-a")
+          | Map.lookup (name "blocked-b") changes /= Just Remove = pure $ Planner.CompilationFailure (failure "blocked-b")
+          | otherwise = pure Planner.Compiles
+        plan = Run.extract $ Planner.planPackageSetWith probe packageSet manifests candidates
+        intervention = Utils.fromJust "Missing iterative-removal intervention." $ Array.head plan.manualInterventions
+
+      intervention.removals `Assert.shouldEqual` [ name "blocked-a", name "blocked-b" ]
+      intervention.targets `Assert.shouldEqual` [ name "target" ]
+      intervention.verification `Assert.shouldEqual` { error: Nothing, status: "verified" }
+      String.contains (String.Pattern "blocked-b@1.0.0") (fromMaybe "" intervention.compilerError)
+        `Assert.shouldEqual` true
+
+  Spec.describe "version-check GitHub issue reconciliation" do
+    Spec.it "decodes GitHub's pull_request field before filtering issues" do
+      let request = Octokit.listIssuesRequest { owner: "purescript", repo: "registry-dev" }
+      let response = """[{"body":null,"number":786,"pull_request":{},"state":"open","title":"PR"}]"""
+      case parseJson request.codec response of
+        Right [ decoded ] -> decoded.isPullRequest `Assert.shouldEqual` true
+        _ -> Assert.fail "Expected a GitHub pull request to decode as a pull request."
+
+    Spec.it "creates the marked issues, is idempotent, and reopens an active decision" do
+      let input = githubReconciliationInput true
+      let initial = Utils.fromRight "Could not plan initial issue creation." $ VersionCheck.GitHub.planIssueReconciliation input []
+      case initial of
+        [ VersionCheck.GitHub.CreateIssue summary, VersionCheck.GitHub.CreateIssue decision ] -> do
+          summary.title `Assert.shouldEqual` "Package set planning report"
+          String.contains (String.Pattern VersionCheck.GitHub.summaryMarker) summary.body `Assert.shouldEqual` true
+          String.contains (String.Pattern VersionCheck.GitHub.decisionMarker) decision.body `Assert.shouldEqual` true
+
+          let
+            existing =
+              [ issue 1 "open" summary.title summary.body
+              , issue 2 "open" decision.title decision.body
+              ]
+          case VersionCheck.GitHub.planIssueReconciliation input existing of
+            Right [] -> pure unit
+            _ -> Assert.fail "Expected issue reconciliation to be idempotent."
+
+          let closed = [ issue 1 "open" summary.title summary.body, issue 2 "closed" decision.title decision.body ]
+          case VersionCheck.GitHub.planIssueReconciliation input closed of
+            Right [ VersionCheck.GitHub.UpdateIssue update ] -> do
+              (update.issue == IssueNumber 2) `Assert.shouldEqual` true
+              update.state `Assert.shouldEqual` "open"
+            _ -> Assert.fail "Expected the active closed decision issue to be reopened."
+        _ -> Assert.fail "Expected the initial summary and decision issue mutations."
+
+    Spec.it "updates only the rolling summary when decision reconciliation is unsafe" do
+      let input = githubReconciliationInput false
+      case VersionCheck.GitHub.planIssueReconciliation input [] of
+        Right [ VersionCheck.GitHub.CreateIssue created ] ->
+          created.title `Assert.shouldEqual` "Package set planning report"
+        _ -> Assert.fail "Expected only the rolling summary issue to be created."
+
+    Spec.it "ignores pull requests and refuses fingerprint ownership conflicts" do
+      let input = githubReconciliationInput true
+      let pullRequest = (issue 1 "open" "Pull request" (decisionIssueBody "other-component" "sha256-fingerprint=")) { isPullRequest = true }
+      case VersionCheck.GitHub.planIssueReconciliation input [ pullRequest ] of
+        Right [ VersionCheck.GitHub.CreateIssue _, VersionCheck.GitHub.CreateIssue _ ] -> pure unit
+        _ -> Assert.fail "Expected pull requests to be excluded from issue reconciliation."
+
+      let conflictingIssue = issue 2 "open" "Other decision" (decisionIssueBody "other-component" "sha256-fingerprint=")
+      case VersionCheck.GitHub.planIssueReconciliation input [ conflictingIssue ] of
+        Left error -> String.contains (String.Pattern "belongs to a decision issue for another component") error `Assert.shouldEqual` true
+        Right _ -> Assert.fail "Expected cross-component fingerprint ownership to fail closed."
+
+    Spec.it "refuses malformed automation identity markers" do
+      let input = githubReconciliationInput true
+      let duplicated = decisionIssueBody "other-component" "other-fingerprint" <> "\n" <> VersionCheck.GitHub.componentMarkerPrefix <> "other-component" <> VersionCheck.GitHub.markerSuffix
+      case VersionCheck.GitHub.planIssueReconciliation input [ issue 1 "open" "Malformed" duplicated ] of
+        Left _ -> pure unit
+        Right _ -> Assert.fail "Expected malformed decision markers to fail closed."
+
 type ElmishFixture =
   { candidates :: Array Planner.Candidate
   , manifests :: ManifestIndex
@@ -366,3 +462,34 @@ name = Utils.unsafePackageName
 
 version :: String -> Version
 version = Utils.unsafeVersion
+
+githubReconciliationInput :: Boolean -> VersionCheck.GitHub.ReconciliationInput
+githubReconciliationInput reconcileDecisions =
+  { markdown: "# Current report"
+  , reconcileDecisions
+  , interventions:
+      [ { component: "packages-example-sha256-component"
+        , fingerprint: "sha256-fingerprint="
+        , markdownBody: "Exact compiler evidence."
+        , payload: "{\n  \"packages\": { \"example\": null }\n}"
+        , removalVerified: true
+        , title: "Package set intervention: example"
+        }
+      ]
+  }
+
+issue :: Int -> String -> String -> String -> Issue
+issue number state title body =
+  { body: Just body
+  , isPullRequest: false
+  , number: IssueNumber number
+  , state
+  , title
+  }
+
+decisionIssueBody :: String -> String -> String
+decisionIssueBody component fingerprint = String.joinWith "\n"
+  [ VersionCheck.GitHub.decisionMarker
+  , VersionCheck.GitHub.componentMarkerPrefix <> component <> VersionCheck.GitHub.markerSuffix
+  , VersionCheck.GitHub.fingerprintMarkerPrefix <> fingerprint <> VersionCheck.GitHub.markerSuffix
+  ]

From 2a50471a63f40a8a0e9b308f8ab2547230afafc6 Mon Sep 17 00:00:00 2001
From: Thomas Honeyman <hello@thomashoneyman.com>
Date: Tue, 28 Jul 2026 12:10:07 +0000
Subject: [PATCH 8/8] Recommend package-preserving upgrade paths

---
 scripts/src/PackageSetPlanner.purs   |  24 +-
 scripts/src/VersionCheck.purs        | 389 +++++++++++++++++++++++++--
 scripts/src/VersionCheck/GitHub.purs |  15 +-
 scripts/test/Main.purs               | 114 +++++++-
 4 files changed, 504 insertions(+), 38 deletions(-)

diff --git a/scripts/src/PackageSetPlanner.purs b/scripts/src/PackageSetPlanner.purs
index d5a3d7ca..9ee5ae92 100644
--- a/scripts/src/PackageSetPlanner.purs
+++ b/scripts/src/PackageSetPlanner.purs
@@ -59,6 +59,7 @@ type AutomaticPlan =
 
 type ManualIntervention =
   { compilerError :: Maybe String
+  , directBlockers :: Array PackageName
   , packages :: Map PackageName Version
   , removals :: Array PackageName
   , targets :: Array PackageName
@@ -80,8 +81,8 @@ data ProbeResult
 derive instance Eq ProbeResult
 
 data ManualRemovalResult
-  = RemovalVerified Int (Set PackageName) (Array String)
-  | RemovalFailed Int (Set PackageName) (Array String)
+  = RemovalVerified Int (Set PackageName) (Set PackageName) (Array String)
+  | RemovalFailed Int (Set PackageName) (Set PackageName) (Array String)
   | RemovalAnalysisFailed Int String
   | RemovalSearchTruncated Int
 
@@ -545,6 +546,7 @@ planManualInterventions probe packageSet manifests components automatic = go emp
                           { attempts = state.attempts + 1
                           , interventions = state.interventions <>
                               [ { compilerError: Just compilerError
+                                , directBlockers: Array.fromFoldable seeds
                                 , packages
                                 , removals: []
                                 , targets: Array.fromFoldable $ Map.keys latest
@@ -558,13 +560,14 @@ planManualInterventions probe packageSet manifests components automatic = go emp
                       )
                       rest
                   else do
-                    probeManualRemovals probe packageSet manifests packages removals (state.attempts + 1) >>= case _ of
-                      RemovalVerified attempts verifiedRemovals additionalEvidence ->
+                    probeManualRemovals probe packageSet manifests packages seeds removals (state.attempts + 1) >>= case _ of
+                      RemovalVerified attempts directBlockers verifiedRemovals additionalEvidence ->
                         go
                           ( state
                               { attempts = attempts
                               , interventions = state.interventions <>
                                   [ { compilerError: Just $ combineCompilerEvidence compilerError additionalEvidence
+                                    , directBlockers: Array.fromFoldable directBlockers
                                     , packages
                                     , removals: Array.fromFoldable verifiedRemovals
                                     , targets: Array.fromFoldable $ Map.keys latest
@@ -574,12 +577,13 @@ planManualInterventions probe packageSet manifests components automatic = go emp
                               }
                           )
                           rest
-                      RemovalFailed attempts failedRemovals additionalEvidence ->
+                      RemovalFailed attempts directBlockers failedRemovals additionalEvidence ->
                         go
                           ( state
                               { attempts = attempts
                               , interventions = state.interventions <>
                                   [ { compilerError: Just $ combineCompilerEvidence compilerError additionalEvidence
+                                    , directBlockers: Array.fromFoldable directBlockers
                                     , packages
                                     , removals: Array.fromFoldable failedRemovals
                                     , targets: Array.fromFoldable $ Map.keys latest
@@ -607,33 +611,35 @@ probeManualRemovals
   -> ManifestIndex
   -> Map PackageName Version
   -> Set PackageName
+  -> Set PackageName
   -> Int
   -> Run r ManualRemovalResult
 probeManualRemovals probe packageSet manifests packages = go []
   where
   proposed = applyUpdates packageSet packages
 
-  go evidence removals attempts
+  go evidence directBlockers removals attempts
     | attempts >= manualProbeBudget = pure $ RemovalSearchTruncated attempts
     | otherwise = do
         let changes = map PackageSets.Update packages
         let removalChanges = Map.union (map (const PackageSets.Remove) (Map.fromFoldable (map (\name -> Tuple name unit) (Array.fromFoldable removals)))) changes
         probe packageSet removalChanges >>= case _ of
-          Compiles -> pure $ RemovalVerified (attempts + 1) removals evidence
+          Compiles -> pure $ RemovalVerified (attempts + 1) directBlockers removals evidence
           InfrastructureFailure error -> pure $ RemovalAnalysisFailed (attempts + 1) error
           CompilationFailure error -> do
             let nextEvidence = evidence <> [ error ]
             let remaining = Foldable.foldr Map.delete proposed removals
             let seeds = compilerFailurePackages packageSet packages error
+            let nextDirectBlockers = Set.union directBlockers seeds
             case reverseDependencyClosure remaining manifests seeds of
               Left analysisError -> pure $ RemovalAnalysisFailed (attempts + 1) analysisError
               Right closure -> do
                 let additions = Set.difference closure (Map.keys packages)
                 let next = Set.union removals additions
                 if next == removals then
-                  pure $ RemovalFailed (attempts + 1) removals nextEvidence
+                  pure $ RemovalFailed (attempts + 1) nextDirectBlockers removals nextEvidence
                 else
-                  go nextEvidence next (attempts + 1)
+                  go nextEvidence nextDirectBlockers next (attempts + 1)
 
 combineCompilerEvidence :: String -> Array String -> String
 combineCompilerEvidence initial additional =
diff --git a/scripts/src/VersionCheck.purs b/scripts/src/VersionCheck.purs
index 8ebb0ad3..598947c8 100644
--- a/scripts/src/VersionCheck.purs
+++ b/scripts/src/VersionCheck.purs
@@ -43,10 +43,12 @@ import Registry.App.Effect.Registry (REGISTRY_READ)
 import Registry.App.Effect.Registry as Registry
 import Registry.App.Effect.Storage (STORAGE)
 import Registry.App.Effect.Storage as Storage
+import Registry.App.Legacy.LenientVersion as LenientVersion
 import Registry.Foreign.FSExtra as FS.Extra
-import Registry.Foreign.Octokit (GitHubToken(..))
+import Registry.Foreign.Octokit (GitHubToken(..), Octokit)
 import Registry.Foreign.Octokit as Octokit
 import Registry.Internal.Codec as Internal.Codec
+import Registry.Location (Location(..))
 import Registry.Manifest (Manifest(..))
 import Registry.ManifestIndex (ManifestIndex)
 import Registry.ManifestIndex as ManifestIndex
@@ -95,6 +97,8 @@ main = launchAff_ do
     Right parsed -> pure parsed
 
   resourceEnv <- Env.lookupResourceEnv
+  githubToken <- map GitHubToken <$> liftEffect (Process.lookupEnv "GITHUB_TOKEN")
+  github <- traverse (flip Octokit.newOctokit resourceEnv.githubApiUrl) githubToken
 
   let cache = Path.concat [ scratchDir, ".cache" ]
   FS.Extra.ensureDirectory cache
@@ -113,7 +117,7 @@ main = launchAff_ do
       , cacheRef: registryCacheRef
       }
 
-  runVersionCheck options.submit resourceEnv.registryApiUrl
+  runVersionCheck options.submit github resourceEnv.registryApiUrl
     # PackageSets.interpret (PackageSets.handle { workdir: scratchDir })
     # Except.runExcept
     # Registry.interpretRead (Registry.handleRead registryEnv)
@@ -132,10 +136,9 @@ main = launchAff_ do
         for_ options.markdown \path -> FS.Aff.writeTextFile UTF8 path (markdown <> "\n")
         reconciliationError <-
           if options.reconcileIssues then do
-            token <- liftEffect (Process.lookupEnv "GITHUB_TOKEN") >>= case _ of
+            octokit <- case github of
               Nothing -> Aff.throwError $ Aff.error "GITHUB_TOKEN is required with --reconcile-issues."
-              Just value -> pure $ GitHubToken value
-            octokit <- Octokit.newOctokit token resourceEnv.githubApiUrl
+              Just value -> pure value
             VersionCheck.GitHub.reconcile octokit
               { interventions: result.report.manualInterventions <#> \intervention ->
                   { component: intervention.component
@@ -216,13 +219,44 @@ type ManualAnalysisReport =
   }
 
 type ManualInterventionReport =
-  { component :: String
+  { automaticRecoveryPlan :: Maybe ConditionalPlanReport
+  , bestUpstreamCandidatePlan :: Maybe ConditionalPlanReport
+  , collateralRemovals :: Array PackageName
+  , component :: String
+  , conditionalPlans :: Array ConditionalPlanReport
+  , conditionalSearchTruncated :: Boolean
+  , directBlockers :: Array PackageName
   , fingerprint :: String
   , markdownBody :: String
+  , recommendedConditionalPlan :: Maybe ConditionalPlanReport
   , removal :: { payload :: Operation.PackageSetOperation, verified :: Boolean }
+  , removalScore :: Int
+  , targetUpdates :: Map PackageName Version
   , title :: String
+  , upstreamCandidates :: Array UpstreamCandidateReport
   }
 
+type ConditionalPlanReport =
+  { fixes :: Array PackageName
+  , projectedRemovals :: Array PackageName
+  , projectedRemovalScore :: Int
+  , projectedRescues :: Array PackageName
+  , rescuedScore :: Int
+  }
+
+type UpstreamCandidateReport =
+  { error :: Maybe String
+  , name :: PackageName
+  , releases :: Array UpstreamRelease
+  }
+
+type UpstreamRelease =
+  { ref :: String
+  , version :: Version
+  }
+
+type UpstreamCandidates = Map PackageName { error :: Maybe String, releases :: Array UpstreamRelease }
+
 incompatibilityCodec :: CJ.Codec Incompatibility
 incompatibilityCodec = CJ.named "VersionCheckIncompatibility" $ CJ.Record.object
   { dependency: PackageName.codec
@@ -269,16 +303,48 @@ manualAnalysisCodec = CJ.named "PackageSetManualAnalysis" $ CJ.Record.object
   , searchTruncated: CJ.boolean
   }
 
+conditionalPlanCodec :: CJ.Codec ConditionalPlanReport
+conditionalPlanCodec = CJ.named "PackageSetConditionalPlan" $ CJ.Record.object
+  { fixes: CJ.array PackageName.codec
+  , projectedRemovals: CJ.array PackageName.codec
+  , projectedRemovalScore: CJ.int
+  , projectedRescues: CJ.array PackageName.codec
+  , rescuedScore: CJ.int
+  }
+
+upstreamReleaseCodec :: CJ.Codec UpstreamRelease
+upstreamReleaseCodec = CJ.named "PackageSetUpstreamRelease" $ CJ.Record.object
+  { ref: CJ.string
+  , version: Version.codec
+  }
+
+upstreamCandidateCodec :: CJ.Codec UpstreamCandidateReport
+upstreamCandidateCodec = CJ.named "PackageSetUpstreamCandidate" $ CJ.Record.object
+  { error: CJ.Common.nullable CJ.string
+  , name: PackageName.codec
+  , releases: CJ.array upstreamReleaseCodec
+  }
+
 manualInterventionCodec :: CJ.Codec ManualInterventionReport
 manualInterventionCodec = CJ.named "PackageSetManualIntervention" $ CJ.Record.object
-  { component: CJ.string
+  { automaticRecoveryPlan: CJ.Common.nullable conditionalPlanCodec
+  , bestUpstreamCandidatePlan: CJ.Common.nullable conditionalPlanCodec
+  , collateralRemovals: CJ.array PackageName.codec
+  , component: CJ.string
+  , conditionalPlans: CJ.array conditionalPlanCodec
+  , conditionalSearchTruncated: CJ.boolean
+  , directBlockers: CJ.array PackageName.codec
   , fingerprint: CJ.string
   , markdownBody: CJ.string
+  , recommendedConditionalPlan: CJ.Common.nullable conditionalPlanCodec
   , removal: CJ.Record.object
       { payload: Operation.packageSetOperationCodec
       , verified: CJ.boolean
       }
+  , removalScore: CJ.int
+  , targetUpdates: Internal.Codec.packageMap Version.codec
   , title: CJ.string
+  , upstreamCandidates: CJ.array upstreamCandidateCodec
   }
 
 reportCodec :: CJ.Codec Report
@@ -311,8 +377,8 @@ type VersionCheckResult =
   , submissionError :: Maybe String
   }
 
-runVersionCheck :: Boolean -> URL -> Run VersionCheckEffects VersionCheckResult
-runVersionCheck submit registryApiUrl = do
+runVersionCheck :: Boolean -> Maybe Octokit -> URL -> Run VersionCheckEffects VersionCheckResult
+runVersionCheck submit github registryApiUrl = do
   Log.info "Registry Version Check: compile-guided planning for pending package set updates..."
   packageSet <- Registry.readLatestPackageSet >>= case _ of
     Nothing -> Except.throw "No package set found."
@@ -323,7 +389,8 @@ runVersionCheck submit registryApiUrl = do
   let recent = PackageSetUpdater.selectPackageSetCandidates (PackageSetUpdater.RecentUploads generatedAt (Hours 24.0)) packageSet metadata
   let plannerCandidates = PackageSetUpdater.plannerCandidates packageSet metadata manifests recent
   planning <- Planner.planPackageSet packageSet manifests plannerCandidates
-  report <- buildReport generatedAt packageSet metadata manifests planning
+  upstreamCandidates <- discoverUpstreamCandidates github packageSet metadata planning
+  report <- buildReportWithUpstream upstreamCandidates generatedAt packageSet metadata manifests planning
   Log.info $ "Found " <> show (Array.length report.pending) <> " package versions pending a package set update."
   let
     shouldSubmit =
@@ -354,8 +421,56 @@ runVersionCheck submit registryApiUrl = do
       Right _ -> report
   pure { report: finalReport, submissionError }
 
+discoverUpstreamCandidates
+  :: forall r
+   . Maybe Octokit
+  -> PackageSet
+  -> Map PackageName Metadata
+  -> Planner.Plan
+  -> Run (LOG + AFF + r) UpstreamCandidates
+discoverUpstreamCandidates Nothing _ _ _ = do
+  Log.warn "GITHUB_TOKEN is unavailable; skipping advisory discovery of unregistered upstream tags."
+  pure Map.empty
+discoverUpstreamCandidates (Just octokit) (PackageSet set) metadata planning = do
+  let blockers = Set.fromFoldable $ Array.concatMap _.directBlockers planning.manualInterventions
+  entries <- for (Array.fromFoldable blockers) \name -> do
+    let result error releases = Tuple name { error, releases }
+    case Tuple (Map.lookup name set.packages) (Map.lookup name metadata) of
+      Tuple Nothing _ -> pure $ result (Just "The blocker is not present in the package set.") []
+      Tuple _ Nothing -> pure $ result (Just "Registry metadata is unavailable for this blocker.") []
+      Tuple (Just current) (Just (Metadata packageMetadata)) -> case packageMetadata.location of
+        Git _ -> pure $ result (Just "Upstream tag discovery currently supports GitHub packages only.") []
+        GitHub { owner, repo } -> do
+          Run.liftAff (Octokit.request octokit $ Octokit.listTagsRequest { owner, repo }) >>= case _ of
+            Left error -> do
+              Log.warn $ "Could not discover upstream tags for " <> PackageName.print name <> ": " <> Octokit.printGitHubError error
+              pure $ result (Just "Upstream tag discovery failed; see the workflow log for details.") []
+            Right tags -> do
+              let known = Set.fromFoldable $ Map.keys packageMetadata.published <> Map.keys packageMetadata.unpublished
+              pure $ result Nothing (unregisteredUpstreamReleases current known tags)
+  pure $ Map.fromFoldable entries
+
+unregisteredUpstreamReleases :: Version -> Set Version -> Array Octokit.Tag -> Array UpstreamRelease
+unregisteredUpstreamReleases current known tags = do
+  let
+    releases = Map.values $ Map.fromFoldableWith preferStableRef $ Array.mapMaybe
+      ( \tag -> case LenientVersion.parse tag.name of
+          Left _ -> Nothing
+          Right parsed -> do
+            let version = LenientVersion.version parsed
+            guard $ version > current && not (Set.member version known)
+            pure $ Tuple version { ref: tag.name, version }
+      )
+      tags
+  Array.reverse $ Array.sortWith _.version $ Array.fromFoldable releases
+  where
+  preferStableRef a b = if a.ref <= b.ref then a else b
+
 buildReport :: forall m. MonadEffect m => DateTime -> PackageSet -> Map PackageName Metadata -> ManifestIndex -> Planner.Plan -> m Report
-buildReport generatedAt (PackageSet set) metadata manifests planning = do
+buildReport = buildReportWithUpstream Map.empty
+
+buildReportWithUpstream :: forall m. MonadEffect m => UpstreamCandidates -> DateTime -> PackageSet -> Map PackageName Metadata -> ManifestIndex -> Planner.Plan -> m Report
+buildReportWithUpstream upstreamCandidates generatedAt packageSet@(PackageSet set) metadata manifests planning = do
   let candidates = findCandidates set.compiler set.packages metadata
   let latest = Map.fromFoldable $ candidates <#> \candidate -> Tuple candidate.name candidate.candidate
   let proposed = Map.union latest set.packages
@@ -380,7 +495,7 @@ buildReport generatedAt (PackageSet set) metadata manifests planning = do
       , transitiveDependants: Array.length transitive
       }
   let automatic = planning.automatic
-  manualInterventions <- traverse (manualReport set.version set.compiler) planning.manualInterventions
+  manualInterventions <- traverse (manualReport packageSet manifests upstreamCandidates) planning.manualInterventions
   pure
     { compiler: set.compiler
     , generatedAt
@@ -394,22 +509,26 @@ buildReport generatedAt (PackageSet set) metadata manifests planning = do
     , verification: automatic.verification
     }
 
-manualReport :: forall m. MonadEffect m => Version -> Version -> Planner.ManualIntervention -> m ManualInterventionReport
-manualReport baseline compiler intervention = do
+manualReport :: forall m. MonadEffect m => PackageSet -> ManifestIndex -> UpstreamCandidates -> Planner.ManualIntervention -> m ManualInterventionReport
+manualReport (PackageSet set) manifests discoveredUpstream intervention = do
   let removals = Map.fromFoldable $ intervention.removals <#> \name -> Tuple name Nothing
   let update = { compiler: Nothing, packages: Map.union removals (map Just intervention.packages) }
-  let payload = Operation.PackageSetUpdateFrom baseline update
+  let payload = Operation.PackageSetUpdateFrom set.version update
+  let targetUpdates = Map.filterWithKey (\name _ -> Array.elem name intervention.targets) intervention.packages
   let affectedNames = Array.sort $ map PackageName.print (Map.keys update.packages # Array.fromFoldable)
   let targetNames = Array.sort $ map PackageName.print intervention.targets
+  let directBlockers = Array.sort intervention.directBlockers
+  let collateralRemovals = Array.sort $ Array.filter (not <<< flip Array.elem directBlockers) intervention.removals
+  let proposed = Map.union intervention.packages set.packages
+  let removalScore = weightedRemovalScore proposed manifests intervention.removals
+  let conditional = conditionalPlans proposed manifests intervention.packages directBlockers intervention.removals
+  let recommendedConditionalPlan = conditional.recommended
   let
-    decision = String.joinWith "|"
-      [ Version.print compiler
-      , JSON.print (CJ.encode Operation.packageSetOperationCodec payload)
-      , intervention.verification.status
-      , fromMaybe "" intervention.verification.error
-      , fromMaybe "" intervention.compilerError
-      ]
-  decisionHash <- Sha256.print <$> Sha256.hashString decision
+    upstreamCandidates = directBlockers <#> \name -> do
+      let unavailable = { error: Just "Upstream tags were not checked; set GITHUB_TOKEN to enable discovery.", releases: [] }
+      let candidate = fromMaybe unavailable $ Map.lookup name discoveredUpstream
+      { error: candidate.error, name, releases: candidate.releases }
+  let bestUpstreamCandidatePlan = bestPlanWithUpstreamCandidates upstreamCandidates conditional.frontier
   componentHash <- Sha256.print <$> Sha256.hashString (String.joinWith "|" targetNames)
   let safeComponentHash = componentHash # String.replaceAll (String.Pattern "+") (String.Replacement "-") # String.replaceAll (String.Pattern "/") (String.Replacement "_") # String.replaceAll (String.Pattern "=") (String.Replacement "")
   let component = "packages-" <> String.take 72 (String.joinWith "-" targetNames) <> "-" <> String.take 32 safeComponentHash
@@ -417,13 +536,215 @@ manualReport baseline compiler intervention = do
   let title = String.trim $ String.take 256 $ "Package set intervention: " <> String.joinWith ", " affectedNames
   let
     markdownBody = String.joinWith "\n"
-      [ "The planner tested this component with PureScript `" <> Version.print compiler <> "` against package set `" <> Version.print baseline <> "`."
+      [ "The planner tested this component with PureScript `" <> Version.print set.compiler <> "` against package set `" <> Version.print set.version <> "`."
+      , ""
+      , "## Recommendation"
+      , ""
+      , "Target update: " <> renderUpdatesInline targetUpdates <> "."
+      , case recommendedConditionalPlan of
+          Nothing -> if verified then "No conditional release plan rescues collateral packages. Review the compile-verified removal payload below." else "No compile-verified or high-leverage conditional plan is available."
+          Just plan -> String.joinWith "\n"
+            [ "Prefer compatible releases for " <> renderPackageNames plan.fixes <> " before accepting the removal payload."
+            , "This is the highest-leverage conditional plan: it projects rescuing " <> show (Array.length plan.projectedRescues) <> " packages (weighted score " <> show plan.rescuedScore <> ") and leaves these projected removals: " <> renderPackageNames plan.projectedRemovals <> "."
+            ]
+      , case conditional.automaticRecoveryPlan of
+          Nothing -> "No conditional zero-removal path was found from the current dependency graph."
+          Just plan -> "Zero-removal path: publish/import compatible releases for " <> renderPackageNames plan.fixes <> ". If those releases enter the registry, rerun the planner; only a fresh exact whole-set compile can make the upgrade automatically submit-ready."
+      , case bestUpstreamCandidatePlan, any (isJust <<< _.error) upstreamCandidates of
+          Nothing, true -> "A tagged-upstream preservation plan could not be assessed because release discovery was incomplete."
+          Nothing, false -> "No preservation plan is currently supported by newer unregistered upstream tags."
+          Just plan, _ -> "Best tagged-upstream path: inspect and import compatible releases for " <> renderPackageNames plan.fixes <> ". On the current graph this projects removals of only " <> renderPackageNames plan.projectedRemovals <> ", but tags are not compatibility or publishability proof."
+      , "Conditional plans are dependency-graph projections, **not compile-verified payloads**. Release manifests can change the graph, so every option must be replanned after publication/import."
+      , ""
+      , "## Why the exact plan removes packages"
+      , ""
+      , "Direct compiler blockers: " <> renderPackageNames directBlockers <> "."
+      , "Collateral reverse dependants: " <> renderPackageNames collateralRemovals <> "."
+      , "Exact removal impact: " <> show (Array.length intervention.removals) <> " packages, dependency-weighted score " <> show removalScore <> ". For each affected package, the score counts it plus transitive dependants affected by the same plan; this is a deterministic prioritization heuristic, not a measure of ecosystem importance."
       , ""
-      , if verified then "The removal-containing payload is compile-verified, but requires trustee review because it removes packages and their reverse-dependency closure." else "No compile-verified removal is available. The payload and compiler output below are diagnostic only and must not be applied as a verified plan."
+      , "## Conditional rescue frontier"
+      , ""
+      , if Array.null conditional.plans then "No conditional rescue plan preserves a package from the exact removal closure."
+        else String.joinWith "\n" $ conditional.plans <#> \plan ->
+          "- Release " <> renderPackageNames plan.fixes <> ": rescue " <> renderPackageNames plan.projectedRescues <> " (score " <> show plan.rescuedScore <> "); projected removals " <> renderPackageNames plan.projectedRemovals <> " (score " <> show plan.projectedRemovalScore <> ")."
+      , if conditional.truncated then "\n⚠️ Conditional subset analysis was limited because this component has more than 10 direct blockers." else ""
+      , ""
+      , "## Upstream releases not present in the registry"
+      , ""
+      , renderUpstreamCandidates upstreamCandidates
+      , ""
+      , if verified then "## Compile-verified fallback\n\nThe exact removal-containing payload compiles, but it should be used only if the higher-preservation options above are declined." else "No compile-verified removal is available. The payload and compiler output below are diagnostic only and must not be applied as a verified plan."
       , maybe "" (\error -> "\nCompiler evidence:\n```text\n" <> printableEvidence error <> "\n```") intervention.compilerError
       , maybe "" (\error -> "\nPlanner evidence:\n```text\n" <> printableEvidence error <> "\n```") intervention.verification.error
       ]
-  pure { component, fingerprint: decisionHash, markdownBody, removal: { payload, verified }, title }
+  let
+    decision = String.joinWith "|"
+      [ Version.print set.compiler
+      , JSON.print (CJ.encode Operation.packageSetOperationCodec payload)
+      , intervention.verification.status
+      , markdownBody
+      ]
+  decisionHash <- Sha256.print <$> Sha256.hashString decision
+  pure
+    { automaticRecoveryPlan: conditional.automaticRecoveryPlan
+    , bestUpstreamCandidatePlan
+    , collateralRemovals
+    , component
+    , conditionalPlans: conditional.plans
+    , conditionalSearchTruncated: conditional.truncated
+    , directBlockers
+    , fingerprint: decisionHash
+    , markdownBody
+    , recommendedConditionalPlan
+    , removal: { payload, verified }
+    , removalScore
+    , targetUpdates
+    , title
+    , upstreamCandidates
+    }
+
+conditionalPlans
+  :: Map PackageName Version
+  -> ManifestIndex
+  -> Map PackageName Version
+  -> Array PackageName
+  -> Array PackageName
+  -> { automaticRecoveryPlan :: Maybe ConditionalPlanReport
+     , frontier :: Array ConditionalPlanReport
+     , plans :: Array ConditionalPlanReport
+     , recommended :: Maybe ConditionalPlanReport
+     , truncated :: Boolean
+     }
+conditionalPlans proposed manifests updates directBlockers exactRemovals = do
+  let blockers = Array.sort $ Array.nub directBlockers
+  let truncated = Array.length blockers > 10
+  let fixSets = if truncated then map Array.singleton blockers <> [ blockers ] else nonEmptySubsets blockers
+  let plans = Array.mapMaybe project fixSets
+  let frontier = Array.filter (not <<< flip dominatedBy plans) plans
+  let automaticRecoveryPlan = Array.find (Array.null <<< _.projectedRemovals) $ Array.sortBy compareConditionalPlans frontier
+  { automaticRecoveryPlan
+  , frontier
+  , plans: Array.take 8 $ Array.sortBy compareConditionalPlans frontier
+  , recommended: highestLeveragePlan frontier
+  , truncated
+  }
+  where
+  project fixes = do
+    let remainingBlockers = Set.difference (Set.fromFoldable directBlockers) (Set.fromFoldable fixes)
+    closure <- hush $ Planner.reverseDependencyClosure proposed manifests remainingBlockers
+    guard $ Set.isEmpty $ Set.intersection closure (Map.keys updates)
+    let projected = closure
+    guard $ Set.isEmpty $ Set.intersection projected (Set.fromFoldable fixes)
+    let rescued = Set.difference (Set.fromFoldable exactRemovals) projected
+    guard $ not $ Set.isEmpty rescued
+    pure
+      { fixes: Array.sort fixes
+      , projectedRemovals: Array.fromFoldable projected
+      , projectedRemovalScore: weightedRemovalScore proposed manifests (Array.fromFoldable projected)
+      , projectedRescues: Array.fromFoldable rescued
+      , rescuedScore: weightedRemovalScore proposed manifests (Array.fromFoldable rescued)
+      }
+
+  dominatedBy candidate plans = any (dominates candidate) plans
+
+  dominates candidate other = do
+    let noMoreFixes = Array.length other.fixes <= Array.length candidate.fixes
+    let noMoreRemovals = Array.length other.projectedRemovals <= Array.length candidate.projectedRemovals
+    let noMoreRemovalCost = other.projectedRemovalScore <= candidate.projectedRemovalScore
+    let strictlyBetter = Array.length other.fixes < Array.length candidate.fixes || Array.length other.projectedRemovals < Array.length candidate.projectedRemovals || other.projectedRemovalScore < candidate.projectedRemovalScore
+    other /= candidate && noMoreFixes && noMoreRemovals && noMoreRemovalCost && strictlyBetter
+
+compareConditionalPlans :: ConditionalPlanReport -> ConditionalPlanReport -> Ordering
+compareConditionalPlans a b =
+  compare (Array.length a.fixes) (Array.length b.fixes)
+    <> compare (Array.length a.projectedRemovals) (Array.length b.projectedRemovals)
+    <> compare a.projectedRemovalScore b.projectedRemovalScore
+    <> compare b.rescuedScore a.rescuedScore
+
+highestLeveragePlan :: Array ConditionalPlanReport -> Maybe ConditionalPlanReport
+highestLeveragePlan = Foldable.maximumBy compareLeverage <<< Array.filter materiallyImproves
+  where
+  materiallyImproves plan = Array.length plan.projectedRescues > Array.length plan.fixes
+
+  compareLeverage a b =
+    compare
+      (Array.length a.projectedRescues * Array.length b.fixes)
+      (Array.length b.projectedRescues * Array.length a.fixes)
+      <> compare (a.rescuedScore * Array.length b.fixes) (b.rescuedScore * Array.length a.fixes)
+      <> compare (Array.length b.projectedRemovals) (Array.length a.projectedRemovals)
+      <> compare b.projectedRemovalScore a.projectedRemovalScore
+      <> compare (Array.length b.fixes) (Array.length a.fixes)
+      <> compare (map PackageName.print a.fixes) (map PackageName.print b.fixes)
+
+bestPlanWithUpstreamCandidates :: Array UpstreamCandidateReport -> Array ConditionalPlanReport -> Maybe ConditionalPlanReport
+bestPlanWithUpstreamCandidates upstreamCandidates = Foldable.maximumBy comparePreservation <<< Array.filter isSupported
+  where
+  available = Set.fromFoldable $ Array.mapMaybe availableName upstreamCandidates
+
+  availableName candidate = candidate.name <$ guard (isNothing candidate.error && not (Array.null candidate.releases))
+
+  isSupported plan = all (flip Set.member available) plan.fixes
+
+  comparePreservation a b =
+    compare (Array.length b.projectedRemovals) (Array.length a.projectedRemovals)
+      <> compare b.projectedRemovalScore a.projectedRemovalScore
+      <> compare (Array.length b.fixes) (Array.length a.fixes)
+      <> compare (map PackageName.print a.fixes) (map PackageName.print b.fixes)
+
+weightedRemovalScore :: Map PackageName Version -> ManifestIndex -> Array PackageName -> Int
+weightedRemovalScore packages manifests removals = Foldable.sum $ map weight removals
+  where
+  affected = Set.fromFoldable removals
+  affectedPackages = Map.filterWithKey (\name _ -> Set.member name affected) packages
+
+  weight name = case Planner.reverseDependencyClosure affectedPackages manifests (Set.singleton name) of
+    Left _ -> 1
+    Right closure -> Set.size closure
+
+nonEmptySubsets :: forall a. Array a -> Array (Array a)
+nonEmptySubsets = Array.filter (not <<< Array.null) <<< go
+  where
+  go values = case Array.uncons values of
+    Nothing -> [ [] ]
+    Just { head, tail } -> do
+      let rest = go tail
+      rest <> map (Array.cons head) rest
+
+renderPackageNames :: Array PackageName -> String
+renderPackageNames names
+  | Array.null names = "none"
+  | otherwise = do
+      let visible = Array.take renderedNameLimit names
+      let omitted = Array.length names - Array.length visible
+      String.joinWith ", " (visible <#> \name -> "`" <> PackageName.print name <> "`")
+        <> if omitted > 0 then " (and " <> show omitted <> " more in the JSON report)" else ""
+
+renderUpdatesInline :: Map PackageName Version -> String
+renderUpdatesInline updates
+  | Map.isEmpty updates = "none"
+  | otherwise = do
+      let allUpdates = Map.toUnfoldable updates :: Array (Tuple PackageName Version)
+      let visible = Array.take renderedNameLimit allUpdates
+      let omitted = Array.length allUpdates - Array.length visible
+      String.joinWith ", " (visible <#> \(Tuple name version) -> "`" <> PackageName.print name <> "@" <> Version.print version <> "`")
+        <> if omitted > 0 then " (and " <> show omitted <> " more in the JSON report)" else ""
+
+renderUpstreamCandidates :: Array UpstreamCandidateReport -> String
+renderUpstreamCandidates candidates
+  | Array.null candidates = "No direct compiler blockers were identified."
+  | otherwise = do
+      let visible = Array.take renderedNameLimit candidates
+      let omitted = Array.length candidates - Array.length visible
+      String.joinWith "\n"
+        ( visible <#> \candidate -> case candidate.error, candidate.releases of
+            Just error, _ -> "- `" <> PackageName.print candidate.name <> "`: discovery failed: " <> error
+            Nothing, [] -> "- `" <> PackageName.print candidate.name <> "`: no newer semantic-version tag was found. A new maintainer release is required."
+            Nothing, releases -> "- `" <> PackageName.print candidate.name <> "`: unregistered upstream " <> String.joinWith ", " (Array.take 5 releases <#> \release -> "`" <> release.ref <> "` (" <> Version.print release.version <> ")") <> ". Inspect publishability and compatibility before importing."
+        )
+        <> if omitted > 0 then "\n- _" <> show omitted <> " more direct blockers are available in the JSON report._" else ""
+
+renderedNameLimit :: Int
+renderedNameLimit = 20
 
 -- Compiler history is retained as a diagnostic, but does not gate candidates.
 findCandidates :: Version -> Map PackageName Version -> Map PackageName Metadata -> Array Candidate
@@ -527,7 +848,21 @@ renderMarkdown report = String.joinWith "\n"
   renderManual index intervention = String.joinWith "\n"
     [ "### " <> intervention.title
     , ""
-    , "Compile-verified trustee decision issue " <> show (index + 1) <> "; fingerprint `" <> intervention.fingerprint <> "`."
+    , (if intervention.removal.verified then "Compile-verified trustee decision" else "Unverified trustee diagnostic") <> " " <> show (index + 1) <> "; fingerprint `" <> intervention.fingerprint <> "`."
+    , ""
+    , "- Target update: " <> renderUpdatesInline intervention.targetUpdates
+    , "- Direct compiler blockers: " <> renderPackageNames intervention.directBlockers
+    , "- Collateral reverse dependants: " <> renderPackageNames intervention.collateralRemovals
+    , "- Exact fallback: remove **" <> show (Array.length intervention.directBlockers + Array.length intervention.collateralRemovals) <> "** packages; weighted removal score **" <> show intervention.removalScore <> "**"
+    , case intervention.recommendedConditionalPlan of
+        Nothing -> "- Recommended conditional rescue: none with collateral leverage"
+        Just plan -> "- Highest-leverage rescue: release " <> renderPackageNames plan.fixes <> " to project rescuing " <> show (Array.length plan.projectedRescues) <> " packages (weighted score " <> show plan.rescuedScore <> ")"
+    , case intervention.automaticRecoveryPlan of
+        Nothing -> "- Conditional zero-removal path: none found"
+        Just plan -> "- Conditional zero-removal path: release " <> renderPackageNames plan.fixes <> ", then rerun and compile before automatic submission"
+    , case intervention.bestUpstreamCandidatePlan of
+        Nothing -> "- Best tagged-upstream path: none"
+        Just plan -> "- Best tagged-upstream path: inspect/import " <> renderPackageNames plan.fixes <> "; current-graph projection removes " <> renderPackageNames plan.projectedRemovals
     ]
 
   renderPendingPackages pending
diff --git a/scripts/src/VersionCheck/GitHub.purs b/scripts/src/VersionCheck/GitHub.purs
index 8353aae2..a5dc649f 100644
--- a/scripts/src/VersionCheck/GitHub.purs
+++ b/scripts/src/VersionCheck/GitHub.purs
@@ -127,12 +127,25 @@ planIssueReconciliation input allItems = do
               [ UpdateIssue { issue: issue.number, title: intervention.title, body: intervention.body, state: "open" } ]
         Just _ -> []
 
+      activeComponents = Set.fromFoldable components
+      resolvedMutations = Array.mapMaybe resolved $ Array.fromFoldable $ Map.values indexed.byComponent
+
+      resolved issue = do
+        component <- hush $ oneMarker componentMarkerPrefix issue
+        guard $ issue.state == "open" && not (Set.member component activeComponents)
+        pure $ UpdateIssue
+          { body: fromMaybe "" issue.body
+          , issue: issue.number
+          , state: "closed"
+          , title: issue.title
+          }
+
     for_ planned \intervention -> case Map.lookup intervention.fingerprint indexed.byFingerprint of
       Just owner | Just owner /= Map.lookup intervention.component indexed.byComponent ->
         Left $ "Fingerprint " <> intervention.fingerprint <> " belongs to a decision issue for another component."
       _ -> pure unit
 
-    pure $ summaryMutations <> activeMutations
+    pure $ summaryMutations <> activeMutations <> resolvedMutations
 
 type PreparedIntervention =
   { body :: String
diff --git a/scripts/test/Main.purs b/scripts/test/Main.purs
index 2aa8a6ba..b48477e6 100644
--- a/scripts/test/Main.purs
+++ b/scripts/test/Main.purs
@@ -263,9 +263,17 @@ main = runSpecAndExitProcess [ consoleReporter ] do
       let reportIntervention = Utils.fromJust "Missing report intervention." $ Array.head report.manualInterventions
       let removalPayload = Operation.packageSetUpdateData reportIntervention.removal.payload
       Operation.packageSetUpdateExpectedBaseline reportIntervention.removal.payload `Assert.shouldEqual` Just (version "79.0.0")
+      reportIntervention.directBlockers `Assert.shouldEqual` [ name "elmish-hooks" ]
+      reportIntervention.collateralRemovals `Assert.shouldEqual` [ name "elmish-time-machine" ]
+      let recommended = Utils.fromJust "Missing conditional Elmish rescue." reportIntervention.recommendedConditionalPlan
+      recommended.fixes `Assert.shouldEqual` [ name "elmish-hooks" ]
+      recommended.projectedRemovals `Assert.shouldEqual` []
+      recommended.projectedRescues `Assert.shouldEqual` [ name "elmish-hooks", name "elmish-time-machine" ]
       Map.lookup (name "elmish-hooks") removalPayload.packages `Assert.shouldEqual` Just Nothing
       Map.lookup (name "elmish-time-machine") removalPayload.packages `Assert.shouldEqual` Just Nothing
       reportIntervention.removal.verified `Assert.shouldEqual` true
+      String.contains (String.Pattern "could not be assessed because release discovery was incomplete") reportIntervention.markdownBody
+        `Assert.shouldEqual` true
       String.contains (String.Pattern "Advisory range diagnostics") (VersionCheck.renderMarkdown report)
         `Assert.shouldEqual` true
 
@@ -297,11 +305,108 @@ main = runSpecAndExitProcess [ consoleReporter ] do
         intervention = Utils.fromJust "Missing iterative-removal intervention." $ Array.head plan.manualInterventions
 
       intervention.removals `Assert.shouldEqual` [ name "blocked-a", name "blocked-b" ]
+      intervention.directBlockers `Assert.shouldEqual` [ name "blocked-a", name "blocked-b" ]
       intervention.targets `Assert.shouldEqual` [ name "target" ]
       intervention.verification `Assert.shouldEqual` { error: Nothing, status: "verified" }
       String.contains (String.Pattern "blocked-b@1.0.0") (fromMaybe "" intervention.compilerError)
         `Assert.shouldEqual` true
 
+    Spec.it "ranks the fix that preserves a deep package and its dependants above a shallow fix" do
+      let
+        packages = Map.fromFoldable
+          [ Tuple (name "shallow") (version "1.0.0")
+          , Tuple (name "deep") (version "1.0.0")
+          , Tuple (name "dependant-a") (version "1.0.0")
+          , Tuple (name "dependant-b") (version "1.0.0")
+          ]
+        manifests = manifestIndex
+          [ Utils.unsafeManifest "shallow" "1.0.0" []
+          , Utils.unsafeManifest "deep" "1.0.0" []
+          , Utils.unsafeManifest "dependant-a" "1.0.0" [ Tuple "deep" ">=1.0.0 <2.0.0" ]
+          , Utils.unsafeManifest "dependant-b" "1.0.0" [ Tuple "deep" ">=1.0.0 <2.0.0" ]
+          ]
+        alternatives = VersionCheck.conditionalPlans packages manifests Map.empty
+          [ name "shallow", name "deep" ]
+          [ name "shallow", name "deep", name "dependant-a", name "dependant-b" ]
+        recommended = Utils.fromJust "Missing weighted recommendation." $ VersionCheck.highestLeveragePlan alternatives.plans
+        automaticRecovery = Utils.fromJust "Missing zero-removal recovery." alternatives.automaticRecoveryPlan
+        upstreamCandidates =
+          [ { error: Nothing
+            , name: name "deep"
+            , releases: [ { ref: "v2.0.0", version: version "2.0.0" } ]
+            }
+          , { error: Nothing, name: name "shallow", releases: [] }
+          ]
+        upstreamPlan = Utils.fromJust "Missing tagged-upstream plan." $ VersionCheck.bestPlanWithUpstreamCandidates upstreamCandidates alternatives.frontier
+
+      recommended.fixes `Assert.shouldEqual` [ name "deep" ]
+      recommended.projectedRescues `Assert.shouldEqual` [ name "deep", name "dependant-a", name "dependant-b" ]
+      recommended.projectedRemovals `Assert.shouldEqual` [ name "shallow" ]
+      automaticRecovery.fixes `Assert.shouldEqual` [ name "deep", name "shallow" ]
+      automaticRecovery.projectedRemovals `Assert.shouldEqual` []
+      upstreamPlan.fixes `Assert.shouldEqual` [ name "deep" ]
+      upstreamPlan.projectedRemovals `Assert.shouldEqual` [ name "shallow" ]
+
+    Spec.it "does not recommend a conditional release that only rescues itself" do
+      let
+        packages = Map.singleton (name "leaf") (version "1.0.0")
+        manifests = manifestIndex [ Utils.unsafeManifest "leaf" "1.0.0" [] ]
+        alternatives = VersionCheck.conditionalPlans packages manifests Map.empty [ name "leaf" ] [ name "leaf" ]
+
+      alternatives.recommended `Assert.shouldEqual` Nothing
+      map _.fixes alternatives.plans `Assert.shouldEqual` [ [ name "leaf" ] ]
+
+    Spec.it "handles overlapping blocker closures without double-counting rescued packages" do
+      let
+        packages = Map.fromFoldable
+          [ Tuple (name "blocker-a") (version "1.0.0")
+          , Tuple (name "blocker-b") (version "1.0.0")
+          , Tuple (name "shared-dependant") (version "1.0.0")
+          ]
+        manifests = manifestIndex
+          [ Utils.unsafeManifest "blocker-a" "1.0.0" []
+          , Utils.unsafeManifest "blocker-b" "1.0.0" []
+          , Utils.unsafeManifest "shared-dependant" "1.0.0"
+              [ Tuple "blocker-a" ">=1.0.0 <2.0.0"
+              , Tuple "blocker-b" ">=1.0.0 <2.0.0"
+              ]
+          ]
+        alternatives = VersionCheck.conditionalPlans packages manifests Map.empty
+          [ name "blocker-a", name "blocker-b" ]
+          [ name "blocker-a", name "blocker-b", name "shared-dependant" ]
+        recovery = Utils.fromJust "Missing overlapping-closure recovery." alternatives.automaticRecoveryPlan
+
+      recovery.fixes `Assert.shouldEqual` [ name "blocker-a", name "blocker-b" ]
+      recovery.projectedRescues `Assert.shouldEqual` [ name "blocker-a", name "blocker-b", name "shared-dependant" ]
+      recovery.projectedRemovals `Assert.shouldEqual` []
+
+    Spec.it "marks conditional subset analysis truncated while retaining the zero-removal path" do
+      let
+        blockerNames = map (\index -> "blocker-" <> show index) (Array.range 1 11)
+        blockers = map name blockerNames
+        packages = Map.fromFoldable $ blockers <#> \package -> Tuple package (version "1.0.0")
+        manifests = manifestIndex $ blockerNames <#> \package -> Utils.unsafeManifest package "1.0.0" []
+        alternatives = VersionCheck.conditionalPlans packages manifests Map.empty blockers blockers
+        recovery = Utils.fromJust "Missing truncated zero-removal recovery." alternatives.automaticRecoveryPlan
+
+      alternatives.truncated `Assert.shouldEqual` true
+      recovery.fixes `Assert.shouldEqual` Array.sort blockers
+      recovery.projectedRemovals `Assert.shouldEqual` []
+
+    Spec.it "reports newer semantic tags that have not entered registry metadata" do
+      let
+        tags =
+          [ { name: "v1.2.0", sha: "new", url: "https://example.com/new" }
+          , { name: "1.2.0", sha: "same-version", url: "https://example.com/same-version" }
+          , { name: "v1.1.0", sha: "known", url: "https://example.com/known" }
+          , { name: "not-a-version", sha: "ignored", url: "https://example.com/ignored" }
+          ]
+        releases = VersionCheck.unregisteredUpstreamReleases (version "1.0.0") (Set.singleton $ version "1.1.0") tags
+        reordered = VersionCheck.unregisteredUpstreamReleases (version "1.0.0") (Set.singleton $ version "1.1.0") (Array.reverse tags)
+
+      releases `Assert.shouldEqual` [ { ref: "1.2.0", version: version "1.2.0" } ]
+      reordered `Assert.shouldEqual` releases
+
   Spec.describe "version-check GitHub issue reconciliation" do
     Spec.it "decodes GitHub's pull_request field before filtering issues" do
       let request = Octokit.listIssuesRequest { owner: "purescript", repo: "registry-dev" }
@@ -310,7 +415,7 @@ main = runSpecAndExitProcess [ consoleReporter ] do
         Right [ decoded ] -> decoded.isPullRequest `Assert.shouldEqual` true
         _ -> Assert.fail "Expected a GitHub pull request to decode as a pull request."
 
-    Spec.it "creates the marked issues, is idempotent, and reopens an active decision" do
+    Spec.it "creates marked issues, closes resolved decisions, and reopens active decisions" do
       let input = githubReconciliationInput true
       let initial = Utils.fromRight "Could not plan initial issue creation." $ VersionCheck.GitHub.planIssueReconciliation input []
       case initial of
@@ -328,6 +433,13 @@ main = runSpecAndExitProcess [ consoleReporter ] do
             Right [] -> pure unit
             _ -> Assert.fail "Expected issue reconciliation to be idempotent."
 
+          let resolved = input { interventions = [] }
+          case VersionCheck.GitHub.planIssueReconciliation resolved existing of
+            Right [ VersionCheck.GitHub.UpdateIssue update ] -> do
+              (update.issue == IssueNumber 2) `Assert.shouldEqual` true
+              update.state `Assert.shouldEqual` "closed"
+            _ -> Assert.fail "Expected the resolved decision issue to be closed."
+
           let closed = [ issue 1 "open" summary.title summary.body, issue 2 "closed" decision.title decision.body ]
           case VersionCheck.GitHub.planIssueReconciliation input closed of
             Right [ VersionCheck.GitHub.UpdateIssue update ] -> do