Rename DeriationOutput (in System.Nix.Realisation) to BuildTraceKey

Ericson2314 · Ericson2314 · commit 68c7e47384ad · 2025-11-09T22:17:37.000-05:00
See the change log for detail why.
diff --git a/hnix-store-core/CHANGELOG.md b/hnix-store-core/CHANGELOG.md
@@ -10,6 +10,9 @@
    * `SingleDerivedPath` type with `parseSingleDerivedPath`, `singleDerivedPathToText`
 
 * Changes:
+   * `DerivationOutput` was renamed to `BuildTraceKey`.
+      Firstly, this avoided a conflict of this type used by `Realisation` with the `DerivationOutput` used by `Derivation` --- the latter deserves the name more since it is for `Derivation`.
+      Secondly, I (@Ericson2314) am also working upstream to rename "realisations" to "build trace entries", and the collection of them to a "build trace", and so this brings the naming in line with that.
    * `OutputName.unOutputName` now returns `StorePathName` instead of `Text`
    * `DerivedPath_Built` constructor now takes `SingleDerivedPath` instead of `StorePath`
 
diff --git a/hnix-store-core/src/System/Nix/Build.hs b/hnix-store-core/src/System/Nix/Build.hs
@@ -15,7 +15,7 @@ import Data.Text (Text)
 import GHC.Generics (Generic)
 
 import System.Nix.OutputName (OutputName)
-import System.Nix.Realisation (DerivationOutput, Realisation)
+import System.Nix.Realisation (BuildTraceKey, Realisation)
 
 -- | Mode of the build operation
 -- Keep the order of these Enums to match enums from reference implementations
@@ -59,7 +59,7 @@ data BuildResult = BuildResult
   -- ^ Start time of this build (since 1.29)
   , buildResultStopTime           :: Maybe UTCTime
   -- ^ Stop time of this build (since 1.29)
-  , buildResultBuiltOutputs       :: Maybe (Map (DerivationOutput OutputName) Realisation)
+  , buildResultBuiltOutputs       :: Maybe (Map (BuildTraceKey OutputName) Realisation)
   -- ^ Mapping of the output names to @Realisation@s (since 1.28)
   -- (paths with additional info and their dependencies)
   }
diff --git a/hnix-store-core/src/System/Nix/Realisation.hs b/hnix-store-core/src/System/Nix/Realisation.hs
@@ -3,10 +3,10 @@ Description : Derivation realisations
 -}
 
 module System.Nix.Realisation (
-    DerivationOutput(..)
-  , DerivationOutputError(..)
-  , derivationOutputBuilder
-  , derivationOutputParser
+    BuildTraceKey(..)
+  , BuildTraceKeyError(..)
+  , buildTraceKeyBuilder
+  , buildTraceKeyParser
   , Realisation(..)
   , RealisationWithId(..)
   ) where
@@ -29,75 +29,75 @@ import Data.Text.Lazy.Builder qualified
 import System.Nix.Hash qualified
 
 -- | Output of the derivation
-data DerivationOutput a = DerivationOutput
-  { derivationOutputHash :: DSum HashAlgo Digest
+data BuildTraceKey a = BuildTraceKey
+  { buildTraceKeyHash :: DSum HashAlgo Digest
   -- ^ Hash modulo of the derivation
-  , derivationOutputOutput :: a
+  , buildTraceKeyOutput :: a
   -- ^ Output (either a OutputName or StorePatH)
   } deriving (Eq, Generic, Ord, Show)
 
-data DerivationOutputError
-  = DerivationOutputError_Digest String
-  | DerivationOutputError_Name InvalidNameError
-  | DerivationOutputError_NoExclamationMark
-  | DerivationOutputError_NoColon
-  | DerivationOutputError_TooManyParts [Text]
+data BuildTraceKeyError
+  = BuildTraceKeyError_Digest String
+  | BuildTraceKeyError_Name InvalidNameError
+  | BuildTraceKeyError_NoExclamationMark
+  | BuildTraceKeyError_NoColon
+  | BuildTraceKeyError_TooManyParts [Text]
   deriving (Eq, Ord, Show)
 
-derivationOutputParser
+buildTraceKeyParser
   :: (Text -> Either InvalidNameError outputName)
   -> Text
-  -> Either DerivationOutputError (DerivationOutput outputName)
-derivationOutputParser outputName dOut =
+  -> Either BuildTraceKeyError (BuildTraceKey outputName)
+buildTraceKeyParser outputName dOut =
   case Data.Text.splitOn (Data.Text.singleton '!') dOut of
-    [] -> Left DerivationOutputError_NoColon
+    [] -> Left BuildTraceKeyError_NoColon
     [sriHash, oName] -> do
       hash <-
         case Data.Text.splitOn (Data.Text.singleton ':') sriHash of
-          [] -> Left DerivationOutputError_NoColon
+          [] -> Left BuildTraceKeyError_NoColon
           [hashName, digest] ->
             Data.Bifunctor.first
-              DerivationOutputError_Digest
+              BuildTraceKeyError_Digest
               $ System.Nix.Hash.mkNamedDigest hashName digest
-          x -> Left $ DerivationOutputError_TooManyParts x
+          x -> Left $ BuildTraceKeyError_TooManyParts x
       name <-
         Data.Bifunctor.first
-          DerivationOutputError_Name
+          BuildTraceKeyError_Name
           $ outputName oName
 
-      pure $ DerivationOutput hash name
-    x -> Left $ DerivationOutputError_TooManyParts x
+      pure $ BuildTraceKey hash name
+    x -> Left $ BuildTraceKeyError_TooManyParts x
 
-derivationOutputBuilder
+buildTraceKeyBuilder
   :: (outputName -> Text)
-  -> DerivationOutput outputName
+  -> BuildTraceKey outputName
   -> Builder
-derivationOutputBuilder outputName DerivationOutput{..} =
-     System.Nix.Hash.algoDigestBuilder derivationOutputHash
+buildTraceKeyBuilder outputName BuildTraceKey{..} =
+     System.Nix.Hash.algoDigestBuilder buildTraceKeyHash
   <> Data.Text.Lazy.Builder.singleton '!'
-  <> Data.Text.Lazy.Builder.fromText (outputName derivationOutputOutput)
+  <> Data.Text.Lazy.Builder.fromText (outputName buildTraceKeyOutput)
 
 -- | Build realisation context
 --
 -- realisationId is ommited since it is a key
--- of type @DerivationOutput OutputName@ so
+-- of type @BuildTraceKey OutputName@ so
 -- we will use @RealisationWithId@ newtype
 data Realisation = Realisation
   { realisationOutPath :: StorePath
   -- ^ Output path
   , realisationSignatures :: Set Signature
   -- ^ Signatures
-  , realisationDependencies :: Map (DerivationOutput OutputName) StorePath
+  , realisationDependencies :: Map (BuildTraceKey OutputName) StorePath
   -- ^ Dependent realisations required for this one to be valid
   } deriving (Eq, Generic, Ord, Show)
 
 -- | For wire protocol
 --
 -- We store this normalized in @Build.buildResultBuiltOutputs@
--- as @Map (DerivationOutput OutputName) Realisation@
+-- as @Map (BuildTraceKey OutputName) Realisation@
 -- but wire protocol needs it de-normalized so we
 -- need a special (From|To)JSON instances for it
 newtype RealisationWithId = RealisationWithId
-  { unRealisationWithId :: (DerivationOutput OutputName, Realisation)
+  { unRealisationWithId :: (BuildTraceKey OutputName, Realisation)
   }
   deriving (Eq, Generic, Ord, Show)
diff --git a/hnix-store-json/src/System/Nix/JSON.hs b/hnix-store-json/src/System/Nix/JSON.hs
@@ -36,7 +36,7 @@ import System.Nix.DerivedPath (DerivedPath(..), OutputsSpec(..), SingleDerivedPa
 import System.Nix.Hash
 import System.Nix.OutputName (OutputName)
 import System.Nix.OutputName qualified
-import System.Nix.Realisation (DerivationOutput(..), Realisation, RealisationWithId(..))
+import System.Nix.Realisation (BuildTraceKey(..), Realisation, RealisationWithId(..))
 import System.Nix.Realisation qualified
 import System.Nix.Signature (Signature)
 import System.Nix.Signature qualified
@@ -97,46 +97,46 @@ deriving newtype instance ToJSON OutputName
 deriving newtype instance FromJSONKey OutputName
 deriving newtype instance ToJSONKey OutputName
 
-instance ToJSON (DerivationOutput OutputName) where
+instance ToJSON (BuildTraceKey OutputName) where
   toJSON =
     toJSON
     . Data.Text.Lazy.toStrict
     . Data.Text.Lazy.Builder.toLazyText
-    . System.Nix.Realisation.derivationOutputBuilder
+    . System.Nix.Realisation.buildTraceKeyBuilder
         (System.Nix.StorePath.unStorePathName . System.Nix.OutputName.unOutputName)
 
   toEncoding =
     toEncoding
     . Data.Text.Lazy.toStrict
     . Data.Text.Lazy.Builder.toLazyText
-    . System.Nix.Realisation.derivationOutputBuilder
+    . System.Nix.Realisation.buildTraceKeyBuilder
         (System.Nix.StorePath.unStorePathName . System.Nix.OutputName.unOutputName)
 
-instance ToJSONKey (DerivationOutput OutputName) where
+instance ToJSONKey (BuildTraceKey OutputName) where
   toJSONKey =
     Data.Aeson.Types.toJSONKeyText
     $ Data.Text.Lazy.toStrict
     . Data.Text.Lazy.Builder.toLazyText
-    . System.Nix.Realisation.derivationOutputBuilder
+    . System.Nix.Realisation.buildTraceKeyBuilder
         (System.Nix.StorePath.unStorePathName . System.Nix.OutputName.unOutputName)
 
-instance FromJSON (DerivationOutput OutputName) where
+instance FromJSON (BuildTraceKey OutputName) where
   parseJSON =
-    withText "DerivationOutput OutputName"
+    withText "BuildTraceKey OutputName"
     ( either
         (fail . show)
         pure
-    . System.Nix.Realisation.derivationOutputParser
+    . System.Nix.Realisation.buildTraceKeyParser
         System.Nix.OutputName.mkOutputName
     )
 
-instance FromJSONKey (DerivationOutput OutputName) where
+instance FromJSONKey (BuildTraceKey OutputName) where
   fromJSONKey =
     FromJSONKeyTextParser
     ( either
         (fail . show)
         pure
-    . System.Nix.Realisation.derivationOutputParser
+    . System.Nix.Realisation.buildTraceKeyParser
         System.Nix.OutputName.mkOutputName
     )
 
@@ -265,8 +265,8 @@ deriving
   instance FromJSON Realisation
 
 -- For a keyed version of Realisation
--- we use RealisationWithId (DerivationOutput OutputName, Realisation)
--- instead of Realisation.id :: (DerivationOutput OutputName)
+-- we use RealisationWithId (BuildTraceKey OutputName, Realisation)
+-- instead of Realisation.id :: (BuildTraceKey OutputName)
 -- field.
 instance ToJSON RealisationWithId where
   toJSON (RealisationWithId (drvOut, r)) =
diff --git a/hnix-store-json/tests/JSONSpec.hs b/hnix-store-json/tests/JSONSpec.hs
@@ -12,7 +12,7 @@ import System.Nix.ContentAddress (ContentAddress)
 import System.Nix.DerivedPath (DerivedPath, OutputsSpec, SingleDerivedPath)
 import System.Nix.JSON ({-HashJSON-})
 import System.Nix.OutputName (OutputName)
-import System.Nix.Realisation (DerivationOutput, Realisation)
+import System.Nix.Realisation (BuildTraceKey, Realisation)
 import System.Nix.Signature (Signature)
 import System.Nix.StorePath (StorePath, StorePathName, StorePathHashPart)
 
@@ -37,6 +37,6 @@ spec = do
     prop "OutputsSpec" $ roundtripsJSON @OutputsSpec
     prop "SingleDerivedPath" $ roundtripsJSON @SingleDerivedPath
     prop "DerivedPath" $ roundtripsJSON @DerivedPath
-    prop "DerivationOutput OutputName" $ roundtripsJSON @(DerivationOutput OutputName)
+    prop "BuildTraceKey OutputName" $ roundtripsJSON @(BuildTraceKey OutputName)
     prop "Signature" $ roundtripsJSON @Signature
     prop "Realisation" $ roundtripsJSON @Realisation
diff --git a/hnix-store-json/tests/RealisationSpec.hs b/hnix-store-json/tests/RealisationSpec.hs
@@ -14,18 +14,18 @@ import Test.Hspec.Nix (forceRight)
 import System.Nix.Hash qualified
 import System.Nix.JSON ()
 import System.Nix.OutputName qualified
-import System.Nix.Realisation (DerivationOutput(..), Realisation(..), RealisationWithId(..))
+import System.Nix.Realisation (BuildTraceKey(..), Realisation(..), RealisationWithId(..))
 import System.Nix.Signature qualified
 import System.Nix.StorePath qualified
 
-sampleDerivationOutput :: DerivationOutput System.Nix.OutputName.OutputName
-sampleDerivationOutput = DerivationOutput
-  { derivationOutputHash =
+sampleBuildTraceKey :: BuildTraceKey System.Nix.OutputName.OutputName
+sampleBuildTraceKey = BuildTraceKey
+  { buildTraceKeyHash =
       forceRight
       $ System.Nix.Hash.mkNamedDigest
           "sha256"
           "1b4sb93wp679q4zx9k1ignby1yna3z7c4c2ri3wphylbc2dwsys0"
-  , derivationOutputOutput =
+  , buildTraceKeyOutput =
       forceRight
       $ System.Nix.OutputName.mkOutputName "foo"
   }
@@ -55,7 +55,7 @@ sampleRealisation1 = Realisation
           ]
   , realisationDependencies =
       Data.Map.fromList
-      [ ( sampleDerivationOutput
+      [ ( sampleBuildTraceKey
         , forceRight
           $ System.Nix.StorePath.parseBasePathFromText
               "9472ijanf79nlkb5n1yh57s7867p1930-testFixed"
@@ -66,13 +66,13 @@ sampleRealisation1 = Realisation
 -- upstream-nix/src/libstore-tests/data/realisation/simple.json
 upstreamSimpleRealisation :: RealisationWithId
 upstreamSimpleRealisation = RealisationWithId
-  ( DerivationOutput
-      { derivationOutputHash =
+  ( BuildTraceKey
+      { buildTraceKeyHash =
           forceRight
           $ System.Nix.Hash.mkNamedDigest
               "sha256"
               "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
-      , derivationOutputOutput =
+      , buildTraceKeyOutput =
           forceRight
           $ System.Nix.OutputName.mkOutputName "foo"
       }
@@ -88,13 +88,13 @@ upstreamSimpleRealisation = RealisationWithId
 -- upstream-nix/src/libstore-tests/data/realisation/with-dependent-realisations.json
 upstreamWithDependentRealisations :: RealisationWithId
 upstreamWithDependentRealisations = RealisationWithId
-  ( DerivationOutput
-      { derivationOutputHash =
+  ( BuildTraceKey
+      { buildTraceKeyHash =
           forceRight
           $ System.Nix.Hash.mkNamedDigest
               "sha256"
               "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
-      , derivationOutputOutput =
+      , buildTraceKeyOutput =
           forceRight
           $ System.Nix.OutputName.mkOutputName "foo"
       }
@@ -105,13 +105,13 @@ upstreamWithDependentRealisations = RealisationWithId
       , realisationSignatures = mempty
       , realisationDependencies =
           Data.Map.fromList
-          [ ( DerivationOutput
-                { derivationOutputHash =
+          [ ( BuildTraceKey
+                { buildTraceKeyHash =
                     forceRight
                     $ System.Nix.Hash.mkNamedDigest
                         "sha256"
                         "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
-                , derivationOutputOutput =
+                , buildTraceKeyOutput =
                     forceRight
                     $ System.Nix.OutputName.mkOutputName "foo"
                 }
@@ -125,8 +125,8 @@ upstreamWithDependentRealisations = RealisationWithId
 spec :: Spec
 spec = do
   describe "ground truth" $ do
-    it "sampleDerivationOutput matches preimage" $
-      encode sampleDerivationOutput `shouldBe` "\"sha256:1b4sb93wp679q4zx9k1ignby1yna3z7c4c2ri3wphylbc2dwsys0!foo\""
+    it "sampleBuildTraceKey matches preimage" $
+      encode sampleBuildTraceKey `shouldBe` "\"sha256:1b4sb93wp679q4zx9k1ignby1yna3z7c4c2ri3wphylbc2dwsys0!foo\""
 
     it "sampleRealisation0 matches preimage (relative paths)" $
       encode sampleRealisation0 `shouldBe` "{\"outPath\":\"cdips4lakfk1qbf1x68fq18wnn3r5r14-builder.sh\",\"signatures\":[],\"dependentRealisations\":{}}"
diff --git a/hnix-store-remote/src/System/Nix/Store/Remote/Serializer.hs b/hnix-store-remote/src/System/Nix/Store/Remote/Serializer.hs
diff --git a/hnix-store-tests/src/System/Nix/Arbitrary/Realisation.hs b/hnix-store-tests/src/System/Nix/Arbitrary/Realisation.hs
diff --git a/hnix-store-tests/tests/RealisationSpec.hs b/hnix-store-tests/tests/RealisationSpec.hs
