fix!: make datastore delete inputs JSON-deserializable (#87)

The Input types for the three datastore delete changesets and their
matching operations declared their key slices as `[]cldfdatastore.XKey`,
where `XKey` is a framework interface with unexported implementations.
`encoding/json` cannot unmarshal a JSON array into a slice of interface
values, so any YAML/JSON pipeline driving these changesets failed at the
deserialization boundary, and operation reports could not be re-executed
from disk.

Introduce `datastore/internal/keys/` with plain-DTO mirrors
(`ChainMetadataKey`, `ContractMetadataKey`, `AddressRefKey`) of the
framework key interfaces. Each exposes `ToFrameworkKey()` for conversion
at the boundary; only `AddressRefKey.ToFrameworkKey()` can fail (returns
`ErrAddressRefVersionRequired` when `Version` is nil). The six in-scope
input fields (three changesets, three operations) now hold `[]keys.X`
instead of `[]cldfdatastore.X`. The earlier inline `DeleteAddressRefKey`
from PR #84 is removed in favor of the shared `keys.AddressRefKey`.

Adds JSON-round-trip regression tests for each key type, JSON-driven
end-to-end tests for each delete changeset, and operation-report
round-trip tests for each delete operation.

BREAKING CHANGE: `DeleteChainMetadataChangesetInput.ChainMetadataKeys`,
`DeleteContractMetadataChangesetInput.ContractMetadataKeys`, and
`DeleteAddressRefChangesetInput.AddressRefKeys` — plus the matching
operation Input fields — now hold concrete key structs instead of the
framework interface. The `DeleteAddressRefKey` type previously exported
from `datastore/changesets/` is removed. In-Go callers should switch to
JSON construction (no in-tree callers in chainlink-deployments today).

Author: giogam

datastore/changesets/delete_address_ref.go

@@ -4,48 +4,33 @@ import (
 	"errors"
 	"fmt"
 
-	"github.com/Masterminds/semver/v3"
 	cldfdatastore "github.com/smartcontractkit/chainlink-deployments-framework/datastore"
 	cldf "github.com/smartcontractkit/chainlink-deployments-framework/deployment"
 	cldfops "github.com/smartcontractkit/chainlink-deployments-framework/operations"
 
+	"github.com/smartcontractkit/cld-changesets/datastore/internal/keys"
 	"github.com/smartcontractkit/cld-changesets/datastore/operations"
 )
 
 // DeleteAddressRefChangeset deletes address ref entries from the Datastore.
 type DeleteAddressRefChangeset struct{}
 
 type DeleteAddressRefChangesetInput struct {
-	AddressRefKeys []DeleteAddressRefKey `json:"addressRefKeys"`
-}
-
-type DeleteAddressRefKey struct {
-	ChainSelector uint64                     `json:"chainSelector"`
-	Type          cldfdatastore.ContractType `json:"type"`
-	Version       *semver.Version            `json:"version"`
-	Qualifier     string                     `json:"qualifier"`
-}
-
-func (k DeleteAddressRefKey) addressRefKey() (cldfdatastore.AddressRefKey, error) {
-	if k.Version == nil {
-		return nil, cldfdatastore.ErrAddressRefVersionRequired
-	}
-
-	return cldfdatastore.NewAddressRefKey(k.ChainSelector, k.Type, k.Version, k.Qualifier), nil
+	AddressRefKeys []keys.AddressRefKey `json:"addressRefKeys"`
 }
 
 func (i DeleteAddressRefChangesetInput) addressRefKeys() ([]cldfdatastore.AddressRefKey, error) {
-	keys := make([]cldfdatastore.AddressRefKey, 0, len(i.AddressRefKeys))
+	fwKeys := make([]cldfdatastore.AddressRefKey, 0, len(i.AddressRefKeys))
 	for idx, inputKey := range i.AddressRefKeys {
-		key, err := inputKey.addressRefKey()
+		key, err := inputKey.ToFrameworkKey()
 		if err != nil {
 			return nil, fmt.Errorf("addressRefKeys[%d]: %w", idx, err)
 		}
 
-		keys = append(keys, key)
+		fwKeys = append(fwKeys, key)
 	}
 
-	return keys, nil
+	return fwKeys, nil
 }
 
 // VerifyPreconditions ensures the input is valid.
@@ -57,12 +42,12 @@ func (DeleteAddressRefChangeset) VerifyPreconditions(e cldf.Environment, input D
 		return errors.New("missing datastore in environment")
 	}
 
-	keys, err := input.addressRefKeys()
+	fwKeys, err := input.addressRefKeys()
 	if err != nil {
 		return fmt.Errorf("invalid address ref keys input: %w", err)
 	}
 
-	for _, key := range keys {
+	for _, key := range fwKeys {
 		_, err := e.DataStore.Addresses().Get(key)
 		if err != nil {
 			if errors.Is(err, cldfdatastore.ErrAddressRefNotFound) {
@@ -80,12 +65,12 @@ func (DeleteAddressRefChangeset) VerifyPreconditions(e cldf.Environment, input D
 
 // Apply executes the changeset, staging the address refs to be deleted from the Datastore.
 func (DeleteAddressRefChangeset) Apply(e cldf.Environment, input DeleteAddressRefChangesetInput) (cldf.ChangesetOutput, error) {
-	deps := operations.DeleteAddressRefDeps{DataStore: e.DataStore}
-	addressRefKeys, err := input.addressRefKeys()
-	if err != nil {
+	if _, err := input.addressRefKeys(); err != nil {
 		return cldf.ChangesetOutput{}, fmt.Errorf("invalid address ref keys input: %w", err)
 	}
-	opInput := operations.DeleteAddressRefInput{AddressRefKeys: addressRefKeys}
+
+	deps := operations.DeleteAddressRefDeps{DataStore: e.DataStore}
+	opInput := operations.DeleteAddressRefInput{AddressRefKeys: input.AddressRefKeys}
 
 	report, err := cldfops.ExecuteOperation(e.OperationsBundle, operations.DeleteAddressRefOp, deps, opInput)
 	out := cldf.ChangesetOutput{

datastore/changesets/delete_address_ref_test.go

@@ -1,6 +1,7 @@
 package changesets
 
 import (
+	"encoding/json"
 	"fmt"
 	"testing"
 
@@ -11,6 +12,8 @@ import (
 	cldf "github.com/smartcontractkit/chainlink-deployments-framework/deployment"
 	cldfoperations "github.com/smartcontractkit/chainlink-deployments-framework/operations"
 	cldflogger "github.com/smartcontractkit/chainlink-deployments-framework/pkg/logger"
+
+	"github.com/smartcontractkit/cld-changesets/datastore/internal/keys"
 )
 
 func TestDeleteAddressRefChangeset_VerifyPreconditions(t *testing.T) {
@@ -32,14 +35,14 @@ func TestDeleteAddressRefChangeset_VerifyPreconditions(t *testing.T) {
 				DataStore: testDataStoreWithAddressRefs(t, addressRef1).Seal(),
 			},
 			input: DeleteAddressRefChangesetInput{
-				AddressRefKeys: []DeleteAddressRefKey{deleteAddressRefKey(addressRef1), deleteAddressRefKey(addressRef2)},
+				AddressRefKeys: []keys.AddressRefKey{addressRefKey(addressRef1), addressRefKey(addressRef2)},
 			},
 		},
 		{
 			name: "failure: missing datastore",
 			env:  cldf.Environment{},
 			input: DeleteAddressRefChangesetInput{
-				AddressRefKeys: []DeleteAddressRefKey{deleteAddressRefKey(addressRef1), deleteAddressRefKey(addressRef2)},
+				AddressRefKeys: []keys.AddressRefKey{addressRefKey(addressRef1), addressRefKey(addressRef2)},
 			},
 			wantErr: "missing datastore in environment",
 		},
@@ -48,15 +51,15 @@ func TestDeleteAddressRefChangeset_VerifyPreconditions(t *testing.T) {
 			env: cldf.Environment{
 				DataStore: cldfdatastore.NewMemoryDataStore().Seal(),
 			},
-			input:   DeleteAddressRefChangesetInput{AddressRefKeys: []DeleteAddressRefKey{}},
+			input:   DeleteAddressRefChangesetInput{AddressRefKeys: []keys.AddressRefKey{}},
 			wantErr: "missing address ref keys input",
 		},
 		{
 			name: "failure: address ref entry does not exist",
 			env: cldf.Environment{
 				DataStore: cldfdatastore.NewMemoryDataStore().Seal(),
 			},
-			input:   DeleteAddressRefChangesetInput{AddressRefKeys: []DeleteAddressRefKey{deleteAddressRefKey(addressRef2)}},
+			input:   DeleteAddressRefChangesetInput{AddressRefKeys: []keys.AddressRefKey{addressRefKey(addressRef2)}},
 			wantErr: fmt.Sprintf("address ref entry for chain selector %v, type %v, version %v and qualifier %q does not exist", addressRef2.ChainSelector, addressRef2.Type, addressRef2.Version, addressRef2.Qualifier),
 		},
 	}
@@ -79,7 +82,7 @@ func TestDeleteAddressRefChangeset_MissingVersion(t *testing.T) {
 	t.Parallel()
 
 	input := DeleteAddressRefChangesetInput{
-		AddressRefKeys: []DeleteAddressRefKey{{
+		AddressRefKeys: []keys.AddressRefKey{{
 			ChainSelector: 1234,
 			Type:          "MyContract",
 			Qualifier:     "q1",
@@ -117,7 +120,7 @@ func TestDeleteAddressRefChangeset_Apply(t *testing.T) {
 				OperationsBundle: cldfoperations.NewBundle(t.Context, cldflogger.Test(t), cldfoperations.NewMemoryReporter()),
 			},
 			input: DeleteAddressRefChangesetInput{
-				AddressRefKeys: []DeleteAddressRefKey{deleteAddressRefKey(addressRef1), deleteAddressRefKey(addressRef2)},
+				AddressRefKeys: []keys.AddressRefKey{addressRefKey(addressRef1), addressRefKey(addressRef2)},
 			},
 			wantDeletedKeys: []string{addressRef1.Key().String(), addressRef2.Key().String()},
 		},
@@ -141,8 +144,37 @@ func TestDeleteAddressRefChangeset_Apply(t *testing.T) {
 	}
 }
 
-func deleteAddressRefKey(ref cldfdatastore.AddressRef) DeleteAddressRefKey {
-	return DeleteAddressRefKey{
+func TestDeleteAddressRefChangeset_JSONRoundTrip(t *testing.T) {
+	t.Parallel()
+
+	version := semver.MustParse("1.0.0")
+	addressRef1 := cldfdatastore.AddressRef{Address: "0x01", ChainSelector: 1234, Type: "MyContract", Version: version, Qualifier: "q1"}
+	addressRef2 := cldfdatastore.AddressRef{Address: "0x02", ChainSelector: 5678, Type: "OtherContract", Version: version, Qualifier: ""}
+
+	raw := `{"addressRefKeys":[{"chainSelector":1234,"type":"MyContract","version":"1.0.0","qualifier":"q1"},{"chainSelector":5678,"type":"OtherContract","version":"1.0.0","qualifier":""}]}`
+
+	var got DeleteAddressRefChangesetInput
+	require.NoError(t, json.Unmarshal([]byte(raw), &got))
+	require.Equal(t, []keys.AddressRefKey{addressRefKey(addressRef1), addressRefKey(addressRef2)}, got.AddressRefKeys)
+
+	env := cldf.Environment{
+		DataStore:        testDataStoreWithAddressRefs(t, addressRef1, addressRef2).Seal(),
+		OperationsBundle: cldfoperations.NewBundle(t.Context, cldflogger.Test(t), cldfoperations.NewMemoryReporter()),
+	}
+
+	require.NoError(t, DeleteAddressRefChangeset{}.VerifyPreconditions(env, got))
+
+	out, err := DeleteAddressRefChangeset{}.Apply(env, got)
+	require.NoError(t, err)
+	memDS := out.DataStore.(*cldfdatastore.MemoryDataStore)
+	require.ElementsMatch(t,
+		[]string{addressRef1.Key().String(), addressRef2.Key().String()},
+		memDS.AddressRefStore.DeletedRemoteKeys,
+	)
+}
+
+func addressRefKey(ref cldfdatastore.AddressRef) keys.AddressRefKey {
+	return keys.AddressRefKey{
 		ChainSelector: ref.ChainSelector,
 		Type:          ref.Type,
 		Version:       ref.Version,

datastore/changesets/delete_chain_metadata.go

@@ -8,14 +8,15 @@ import (
 	cldf "github.com/smartcontractkit/chainlink-deployments-framework/deployment"
 	cldfops "github.com/smartcontractkit/chainlink-deployments-framework/operations"
 
+	"github.com/smartcontractkit/cld-changesets/datastore/internal/keys"
 	"github.com/smartcontractkit/cld-changesets/datastore/operations"
 )
 
 // DeleteChainMetadataChangeset deletes chain metadata entries from the Datastore.
 type DeleteChainMetadataChangeset struct{}
 
 type DeleteChainMetadataChangesetInput struct {
-	ChainMetadataKeys []cldfdatastore.ChainMetadataKey `json:"chainMetadataKeys"`
+	ChainMetadataKeys []keys.ChainMetadataKey `json:"chainMetadataKeys"`
 }
 
 // VerifyPreconditions ensures the input is valid.
@@ -28,13 +29,14 @@ func (DeleteChainMetadataChangeset) VerifyPreconditions(e cldf.Environment, inpu
 	}
 
 	for _, key := range input.ChainMetadataKeys {
-		_, err := e.DataStore.ChainMetadata().Get(key)
+		fwKey := key.ToFrameworkKey()
+		_, err := e.DataStore.ChainMetadata().Get(fwKey)
 		if err != nil {
 			if errors.Is(err, cldfdatastore.ErrChainMetadataNotFound) {
-				return fmt.Errorf("chain metadata entry for chain selector %v does not exist", key.ChainSelector())
+				return fmt.Errorf("chain metadata entry for chain selector %v does not exist", fwKey.ChainSelector())
 			}
 
-			return fmt.Errorf("failed to retrieve chain metadata entry for chain selector %v: %w", key.ChainSelector(), err)
+			return fmt.Errorf("failed to retrieve chain metadata entry for chain selector %v: %w", fwKey.ChainSelector(), err)
 		}
 	}
 

datastore/changesets/delete_chain_metadata_test.go

@@ -1,6 +1,7 @@
 package changesets
 
 import (
+	"encoding/json"
 	"fmt"
 	"testing"
 
@@ -10,6 +11,8 @@ import (
 	cldf "github.com/smartcontractkit/chainlink-deployments-framework/deployment"
 	cldfoperations "github.com/smartcontractkit/chainlink-deployments-framework/operations"
 	cldflogger "github.com/smartcontractkit/chainlink-deployments-framework/pkg/logger"
+
+	"github.com/smartcontractkit/cld-changesets/datastore/internal/keys"
 )
 
 func TestDeleteChainMetadataChangeset_VerifyPreconditions(t *testing.T) {
@@ -30,14 +33,14 @@ func TestDeleteChainMetadataChangeset_VerifyPreconditions(t *testing.T) {
 				DataStore: testDataStoreWithChainMetadata(t, chainMetadata1, chainMetadata2).Seal(),
 			},
 			input: DeleteChainMetadataChangesetInput{
-				ChainMetadataKeys: []cldfdatastore.ChainMetadataKey{chainMetadata1.Key(), chainMetadata2.Key()},
+				ChainMetadataKeys: []keys.ChainMetadataKey{{ChainSelector: chainMetadata1.ChainSelector}, {ChainSelector: chainMetadata2.ChainSelector}},
 			},
 		},
 		{
 			name: "failure: missing datastore",
 			env:  cldf.Environment{},
 			input: DeleteChainMetadataChangesetInput{
-				ChainMetadataKeys: []cldfdatastore.ChainMetadataKey{chainMetadata1.Key()},
+				ChainMetadataKeys: []keys.ChainMetadataKey{{ChainSelector: chainMetadata1.ChainSelector}},
 			},
 			wantErr: "missing datastore in environment",
 		},
@@ -46,15 +49,15 @@ func TestDeleteChainMetadataChangeset_VerifyPreconditions(t *testing.T) {
 			env: cldf.Environment{
 				DataStore: cldfdatastore.NewMemoryDataStore().Seal(),
 			},
-			input:   DeleteChainMetadataChangesetInput{ChainMetadataKeys: []cldfdatastore.ChainMetadataKey{}},
+			input:   DeleteChainMetadataChangesetInput{ChainMetadataKeys: []keys.ChainMetadataKey{}},
 			wantErr: "missing chain metadata keys input",
 		},
 		{
 			name: "failure: chain metadata entry does not exist",
 			env: cldf.Environment{
 				DataStore: cldfdatastore.NewMemoryDataStore().Seal(),
 			},
-			input:   DeleteChainMetadataChangesetInput{ChainMetadataKeys: []cldfdatastore.ChainMetadataKey{chainMetadata2.Key()}},
+			input:   DeleteChainMetadataChangesetInput{ChainMetadataKeys: []keys.ChainMetadataKey{{ChainSelector: chainMetadata2.ChainSelector}}},
 			wantErr: fmt.Sprintf("chain metadata entry for chain selector %v does not exist", chainMetadata2.ChainSelector),
 		},
 	}
@@ -93,7 +96,7 @@ func TestDeleteChainMetadataChangeset_Apply(t *testing.T) {
 				OperationsBundle: cldfoperations.NewBundle(t.Context, cldflogger.Test(t), cldfoperations.NewMemoryReporter()),
 			},
 			input: DeleteChainMetadataChangesetInput{
-				ChainMetadataKeys: []cldfdatastore.ChainMetadataKey{chainMetadata1.Key(), chainMetadata2.Key()},
+				ChainMetadataKeys: []keys.ChainMetadataKey{{ChainSelector: chainMetadata1.ChainSelector}, {ChainSelector: chainMetadata2.ChainSelector}},
 			},
 			wantDeletedKeys: []string{chainMetadata1.Key().String(), chainMetadata2.Key().String()},
 		},
@@ -116,3 +119,34 @@ func TestDeleteChainMetadataChangeset_Apply(t *testing.T) {
 		})
 	}
 }
+
+func TestDeleteChainMetadataChangeset_JSONRoundTrip(t *testing.T) {
+	t.Parallel()
+
+	chainMetadata1 := cldfdatastore.ChainMetadata{ChainSelector: 1234, Metadata: "value1"}
+	chainMetadata2 := cldfdatastore.ChainMetadata{ChainSelector: 5678, Metadata: "value2"}
+
+	raw := `{"chainMetadataKeys":[{"chainSelector":1234},{"chainSelector":5678}]}`
+
+	var got DeleteChainMetadataChangesetInput
+	require.NoError(t, json.Unmarshal([]byte(raw), &got))
+	require.Equal(t,
+		[]keys.ChainMetadataKey{{ChainSelector: 1234}, {ChainSelector: 5678}},
+		got.ChainMetadataKeys,
+	)
+
+	env := cldf.Environment{
+		DataStore:        testDataStoreWithChainMetadata(t, chainMetadata1, chainMetadata2).Seal(),
+		OperationsBundle: cldfoperations.NewBundle(t.Context, cldflogger.Test(t), cldfoperations.NewMemoryReporter()),
+	}
+
+	require.NoError(t, DeleteChainMetadataChangeset{}.VerifyPreconditions(env, got))
+
+	out, err := DeleteChainMetadataChangeset{}.Apply(env, got)
+	require.NoError(t, err)
+	memDS := out.DataStore.(*cldfdatastore.MemoryDataStore)
+	require.ElementsMatch(t,
+		[]string{chainMetadata1.Key().String(), chainMetadata2.Key().String()},
+		memDS.ChainMetadataStore.DeletedRemoteKeys,
+	)
+}

datastore/changesets/delete_contract_metadata.go

@@ -8,14 +8,15 @@ import (
 	cldf "github.com/smartcontractkit/chainlink-deployments-framework/deployment"
 	cldfops "github.com/smartcontractkit/chainlink-deployments-framework/operations"
 
+	"github.com/smartcontractkit/cld-changesets/datastore/internal/keys"
 	"github.com/smartcontractkit/cld-changesets/datastore/operations"
 )
 
 // DeleteContractMetadataChangeset deletes contract metadata entries from the Datastore.
 type DeleteContractMetadataChangeset struct{}
 
 type DeleteContractMetadataChangesetInput struct {
-	ContractMetadataKeys []cldfdatastore.ContractMetadataKey `json:"contractMetadataKeys"`
+	ContractMetadataKeys []keys.ContractMetadataKey `json:"contractMetadataKeys"`
 }
 
 // VerifyPreconditions ensures the input is valid.
@@ -28,15 +29,16 @@ func (DeleteContractMetadataChangeset) VerifyPreconditions(e cldf.Environment, i
 	}
 
 	for _, key := range input.ContractMetadataKeys {
-		_, err := e.DataStore.ContractMetadata().Get(key)
+		fwKey := key.ToFrameworkKey()
+		_, err := e.DataStore.ContractMetadata().Get(fwKey)
 		if err != nil {
 			if errors.Is(err, cldfdatastore.ErrContractMetadataNotFound) {
 				return fmt.Errorf("contract metadata entry for chain selector %v and address %v does not exist",
-					key.ChainSelector(), key.Address())
+					fwKey.ChainSelector(), fwKey.Address())
 			}
 
 			return fmt.Errorf("failed to retrieve contract metadata entry for chain selector %v and address %v: %w",
-				key.ChainSelector(), key.Address(), err)
+				fwKey.ChainSelector(), fwKey.Address(), err)
 		}
 	}